Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

28.0 KB
Raw Blame
import { parsePluginObjectUrl, type PluginObjectUrlOptions } from './deliveryObjectUrl.js';
import {
  ghostManifestUsesOidcToken,
  isValidGhostId,
  validateGhostManifest,
  type GhostManifest,
} from './manifest.js';
import {
  PluginProtocolError,
  isoDate,
  nextCursor,
  object,
  sha256,
  string,
} from './internal/parse.js';
import { isValidPluginResourceId } from './internal/pluginResourceId.js';
import { isValidPluginNamespace, parseOptionalNamespace } from './internal/namespace.js';

export {
  AUTHOR_DECLARED_NAMESPACE_REASON,
  authorDeclaredNamespaceReason,
  authorManifestDeclaresNamespace,
  isValidPluginNamespace,
} from './internal/namespace.js';
export { PluginProtocolError } from './internal/parse.js';
export { parsePluginObjectUrl, type PluginObjectUrlOptions } from './deliveryObjectUrl.js';
export { isValidPluginResourceId } from './internal/pluginResourceId.js';

/** Plugin 客户端 HTTP list/detail envelope 版本;与 ghost.json 版本独立演进。 */
export const PLUGIN_API_SCHEMA_VERSION = 2 as const;

/** 客户端请求 Plugin Server 时携带的 Cindy 版本请求头。 */
export const CINDY_CLIENT_VERSION_HEADER = 'x-cindy-version' as const;

/** 普通客户端可见的 Plugin 来源范围。 */
export const PLUGIN_SCOPES = ['public', 'organization', 'personal'] as const;

/** `public` 对所有已登录身份可见;其余范围只对对应组织或自然人可见。 */
export type PluginScope = (typeof PLUGIN_SCOPES)[number];

/**
 * 组织登记的插件前缀(不含尾连字符)。与服务端 `PLUGIN_PREFIX_PATTERN` 一致:
 * 仅小写字母和数字,长度 2–16。
 */
export const PLUGIN_PREFIX_PATTERN = /^[a-z0-9]{2,16}$/;

/** 列表响应当前组织身份与已登记前缀。仅出现在 `GET /api/plugins`。 */
export interface PluginCurrentOrganization {
  /** 当前组织的稳定 ID。 */
  organizationId: string;
  /** Auth 永久组织 slug;旧服务端缺失时保持 undefined。 */
  orgSlug?: string;
  /**
   * 已登记前缀原样保留,不带尾连字符。
   * `null` 表示当前是组织身份,但该组织尚未登记前缀;
   * 与「整段 currentOrganization 为 null」(非组织身份)含义不同。
   */
  pluginPrefix: string | null;
}

/** 服务端为当前客户端选择的 Release 图标元数据;URL 为短期授权地址。 */
export interface PluginIconMetadata {
  /** 图标 MIME 类型,例如 image/png 或 image/svg+xml。 */
  mimeType: string;
  /** 图标对象的 SHA-256,固定为 64 位小写十六进制。 */
  sha256: string;
  /** 图标原始字节数,恒为正整数。 */
  sizeBytes: number;
  /** 短期 HTTPS 图标下载地址。 */
  url: string;
  /** 图标地址过期时间,格式为带毫秒的 UTC ISO 8601。 */
  expiresAt: string;
}

/** 列表和详情共用的客户端兼容 Release 摘要。 */
export interface PluginReleaseSummary {
  /** plugin-server 生成的 Release 资源 ID;调用方应将其视为不透明字符串。 */
  id: string;
  /** 与该 Release 的 `manifest.version` 一致。 */
  version: string;
  /** `.cindy` 原始字节的 SHA-256,固定为 64 位小写十六进制。 */
  sha256: string;
  /** `.cindy` 原始字节数,恒为正整数。 */
  sizeBytes: number;
  /** Release 发布时间,格式为带毫秒的 UTC ISO 8601。 */
  publishedAt: string;
  /** 发布时从包内提取并单独存储的图标;未声明图标时为 null。 */
  icon: PluginIconMetadata | null;
}

/** 详情响应中的客户端兼容 Release;在摘要基础上包含已校验的完整 manifest。 */
export interface PluginReleaseDetail extends PluginReleaseSummary {
  /** 已通过 `validateGhostManifest` 规范化的当前 manifest。 */
  manifest: GhostManifest & { namespace?: string | null };
}

/** Optional aggregate of successfully issued client download URLs, not completed installs. */
export interface PluginDownloadStatistics {
  /** Decimal count of successfully issued download URLs across all releases. */
  requestCount: string;
  /** Rolling 168 hours; optional for compatibility with older servers. */
  last7DaysRequestCount?: string;
}

/** Preserve exact counters while allowing older servers to omit statistics. */
export function parsePluginDownloadStatistics(value: unknown): PluginDownloadStatistics | undefined {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
  const raw = value as Record<string, unknown>;
  const isCount = (count: unknown): count is string =>
    typeof count === 'string' && /^(0|[1-9][0-9]{0,19})$/.test(count);
  if (!isCount(raw.requestCount)) return undefined;
  return {
    requestCount: raw.requestCount,
    ...(isCount(raw.last7DaysRequestCount) ? { last7DaysRequestCount: raw.last7DaysRequestCount } : {}),
  };
}

/** Optional, already-authorized audience aggregate. Downloads are not install receipts. */
export interface PluginUsageStatistics {
  installationCount?: string;
  usageCount?: string;
  usageCountLast7Days?: string;
  asOf: string;
}

/** Invalid optional metrics never make an otherwise compatible marketplace unavailable. */
export function parsePluginUsageStatistics(value: unknown): PluginUsageStatistics | undefined {
  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
  const raw = value as Record<string, unknown>;
  const keys = ['installationCount', 'usageCount', 'usageCountLast7Days'] as const;
  if (typeof raw.asOf !== 'string' || !/^\d{4}-\d{2}-\d{2}T.*Z$/.test(raw.asOf) || !Number.isFinite(Date.parse(raw.asOf))) return undefined;
  const result: PluginUsageStatistics = { asOf: raw.asOf };
  for (const key of keys) {
    if (typeof raw[key] === 'string' && /^(0|[1-9][0-9]{0,19})$/.test(raw[key] as string))
      result[key] = raw[key] as string;
  }
  return keys.some(key => result[key] !== undefined) ? result : undefined;
}

/** Plugin 列表项;只含市场展示和版本对账所需的摘要。 */
export interface VisiblePluginSummary {
  /** plugin-server 生成的永久资源 ID,也是客户端管理安装实例的主键。 */
  id: string;
  /** 包内 `ghost.json.id`;跨不同来源允许重名,不能代替 `id`。 */
  ghostId: string;
  /** 客户端兼容 Release manifest 的展示名。 */
  name: string;
  /** 客户端兼容 Release manifest 的描述;未声明时为 `null`。 */
  description: string | null;
  /** 客户端兼容 Release manifest 的作者;未声明时为 `null`。 */
  author: string | null;
  /** Full workflow-owned nickname; omitted by older servers. */
  displayAuthor?: string | null;
  /** Derived from the verified public authorship binding; not a new database column. */
  publisherKind?: 'official' | 'personal' | null;
  /** Plugin 的来源范围。 */
  scope: PluginScope;
  /** Organization 必须是非空组织 ID;Public 和 Personal 恒为 `null`。 */
  namespace?: string | null;
  organizationId: string | null;
  /** 对当前请求身份计算后的默认安装值,不表示强制安装或强制启用。 */
  defaultInstall: boolean;
  /** 服务端为该客户端选择的 Release;优先 current,不兼容时回退到历史兼容版本。 */
  currentRelease: PluginReleaseSummary;
  usageStatistics?: PluginUsageStatistics;
  downloadStatistics?: PluginDownloadStatistics;
}

/** Plugin 详情;展示字段必须与 `currentRelease.manifest` 保持一致。 */
export interface VisiblePluginDetail {
  /** plugin-server 生成的永久资源 ID,也是客户端管理安装实例的主键。 */
  id: string;
  /** 包内 `ghost.json.id`;跨不同来源允许重名,不能代替 `id`。 */
  ghostId: string;
  /** 客户端兼容 Release manifest 的展示名。 */
  name: string;
  /** 客户端兼容 Release manifest 的描述;未声明时为 `null`。 */
  description: string | null;
  /** 客户端兼容 Release manifest 的作者;未声明时为 `null`。 */
  author: string | null;
  /** Full workflow-owned nickname; omitted by older servers. */
  displayAuthor?: string | null;
  /** Derived from the verified public authorship binding; not a new database column. */
  publisherKind?: 'official' | 'personal' | null;
  /** Plugin 的来源范围。 */
  scope: PluginScope;
  /** Organization 必须是非空组织 ID;Public 和 Personal 恒为 `null`。 */
  namespace?: string | null;
  organizationId: string | null;
  /** 对当前请求身份计算后的默认安装值,不表示强制安装或强制启用。 */
  defaultInstall: boolean;
  /** 服务端为该客户端选择的 Release,包含完整 manifest。 */
  currentRelease: PluginReleaseDetail;
  usageStatistics?: PluginUsageStatistics;
  downloadStatistics?: PluginDownloadStatistics;
}

/** 清理通告支持的处置动作;解析器会跳过动作未知的通告(未来扩展位)。 */
export const PLUGIN_REMOVAL_ACTIONS = ['purge'] as const;

/** `purge` 表示删除本地已安装副本及插件本地数据。 */
export type PluginRemovalAction = (typeof PLUGIN_REMOVAL_ACTIONS)[number];

/** 曾上架、现已下架并被要求处置本地副本的 Plugin 的清理通告。 */
export interface PluginRemovalNotice {
  /** 被清理 Plugin 的永久资源 ID;客户端据此匹配本地安装记录并跨分页去重。 */
  pluginId: string;
  /** 通告对应的 `ghost.json.id` 快照;供客户端双重校验,不能代替 `pluginId`。 */
  ghostId: string;
  /** 被清理 Plugin 的来源范围;当前服务端只对 organization 下发通告。 */
  scope: PluginScope;
  /** Organization 必须是非空组织 ID;Public 和 Personal 恒为 `null`。 */
  namespace?: string | null;
  organizationId: string | null;
  /** 处置动作。 */
  action: PluginRemovalAction;
  /** 最近一次下架时间;重新上架再下架会刷新,消费方不得假设单调。 */
  removedAt: string;
}

/** scope=all 中企业部分被拒绝时的已知错误码。解析器也接受格式合法的未知码。 */
export const ORGANIZATION_PLUGIN_ACCESS_ERROR_CODES = [
  'PLUGIN_NAMESPACE_CLIENT_REQUIRED',
  'PLUGIN_ORGANIZATION_CONTEXT_UNAVAILABLE',
  'PLUGIN_NAMESPACE_CONFIG_REQUIRED',
] as const;

export interface OrganizationPluginAccessError {
  /** 已知码见 ORGANIZATION_PLUGIN_ACCESS_ERROR_CODES;未知但格式合法的码也保留。 */
  code: string;
  message: string;
}

/** Plugin 分页列表响应。 */
export interface ListPluginsResponse {
  /** Plugin HTTP envelope 版本。 */
  schemaVersion: typeof PLUGIN_API_SCHEMA_VERSION;
  /** 当前页内对请求身份可见的 Plugin 摘要。 */
  plugins: VisiblePluginSummary[];
  /** 下一页使用的不透明游标;调用方只可原样回传,没有下一页时为 `null`。 */
  nextCursor: string | null;
  /** 对请求身份可见的清理通告;服务端每页重复完整下发,缺失时规范化为空数组。 */
  removals: PluginRemovalNotice[];
  /**
   * 当前组织身份与已登记插件前缀。匿名 / token 降级 / Personal、以及老服务端缺字段时
   * 规范化为 `null`。组织已登录但未登记前缀时为 `{ organizationId, pluginPrefix: null }`。
   */
  currentOrganization: PluginCurrentOrganization | null;
  /**
   * scope=all 的企业部分被拒绝。每页重复;出现时必须同时有 currentOrganization,
   * 且本页不能有企业条目或清理通告。缺失表示企业部分按原规则返回。
   */
  organizationAccessError?: OrganizationPluginAccessError;
}

/** 单个 Plugin 详情响应。 */
export interface GetPluginResponse {
  /** Plugin HTTP envelope 版本。 */
  schemaVersion: typeof PLUGIN_API_SCHEMA_VERSION;
  /** 当前身份可见且处于 active 状态的 Plugin 详情。 */
  plugin: VisiblePluginDetail;
}

/** 当前 Release 的短期私有下载凭证;不重复携带 HTTP envelope 版本。 */
export interface PluginDownloadResponse {
  pluginId?: string;
  releaseId?: string;
  ghostId?: string;
  namespace?: string | null;
  /** 短期 HTTPS 下载地址。 */
  url: string;
  /** 下载地址过期时间,格式为带毫秒的 UTC ISO 8601。 */
  expiresAt: string;
  /** 必须与客户端准备下载的当前 Release 摘要一致。 */
  sha256: string;
  /** 必须与客户端准备下载的当前 Release 摘要一致。 */
  sizeBytes: number;
}

function parseIconMetadata(value: unknown, path: string, options?: PluginObjectUrlOptions): PluginIconMetadata | null {
  // 老的 v2 服务端尚未提供 icon 字段时,客户端继续使用本地兜底图标。
  if (value === null || value === undefined) return null;
  const raw = object(value, path);
  const mimeType = string(raw.mimeType, `${path}.mimeType`, 128);
  if (!/^image\/[a-z0-9.+-]+$/i.test(mimeType)) {
    throw new PluginProtocolError(`${path}.mimeType 必须是 image/* MIME 类型`);
  }
  if (
    typeof raw.sizeBytes !== 'number' ||
    !Number.isSafeInteger(raw.sizeBytes) ||
    raw.sizeBytes <= 0
  ) {
    throw new PluginProtocolError(`${path}.sizeBytes 必须是正整数`);
  }
  return {
    mimeType,
    sha256: sha256(raw.sha256, `${path}.sha256`),
    sizeBytes: raw.sizeBytes,
    url: parsePluginObjectUrl(raw.url, `${path}.url`, options),
    expiresAt: isoDate(raw.expiresAt, `${path}.expiresAt`),
  };
}

function parseReleaseSummary(value: unknown, path: string, options?: PluginObjectUrlOptions): PluginReleaseSummary {
  const raw = object(value, path);
  const version = string(raw.version, `${path}.version`, 32);
  if (
    typeof raw.sizeBytes !== 'number' ||
    !Number.isSafeInteger(raw.sizeBytes) ||
    raw.sizeBytes <= 0
  ) {
    throw new PluginProtocolError(`${path}.sizeBytes 必须是正整数`);
  }
  return {
    id: string(raw.id, `${path}.id`, 128),
    version,
    sha256: sha256(raw.sha256, `${path}.sha256`),
    sizeBytes: raw.sizeBytes,
    publishedAt: isoDate(raw.publishedAt, `${path}.publishedAt`),
    icon: parseIconMetadata(raw.icon, `${path}.icon`, options),
  };
}

function parseReleaseDetail(value: unknown, ghostId: string, path: string, options?: PluginObjectUrlOptions): PluginReleaseDetail {
  const raw = object(value, path);
  const summary = parseReleaseSummary(raw, path, options);
  const validatedManifest = validateGhostManifest(raw.manifest);
  if (!validatedManifest.ok) {
    throw new PluginProtocolError(`${path}.manifest 不合法: ${validatedManifest.reason}`);
  }
  if (validatedManifest.manifest.id !== ghostId) {
    throw new PluginProtocolError(`${path}.manifest.id 与 ghostId 不一致`);
  }
  if (summary.version !== validatedManifest.manifest.version) {
    throw new PluginProtocolError(`${path}.version 与 manifest.version 不一致`);
  }
  return {
    ...summary,
    manifest: {
      ...validatedManifest.manifest,
      ...parseOptionalNamespace(object(raw.manifest, `${path}.manifest`), `${path}.manifest`),
    },
  };
}

function parseScope(value: unknown, path: string): PluginScope {
  if (!(PLUGIN_SCOPES as readonly unknown[]).includes(value)) {
    throw new PluginProtocolError(`${path}.scope 不合法`);
  }
  return value as PluginScope;
}

function parseScopedOrganizationId(
  scope: PluginScope,
  value: unknown,
  path: string,
): string | null {
  if (
    ((scope === 'public' || scope === 'personal') && value !== null) ||
    (scope === 'organization' && (typeof value !== 'string' || value.length === 0))
  ) {
    throw new PluginProtocolError(`${path}.organizationId 与 scope 不一致`);
  }
  return value as string | null;
}

function parseScopedNamespace(raw: Record<string, unknown>, scope: PluginScope, path: string) {
  const identity = parseOptionalNamespace(raw, path);
  if (
    'namespace' in identity &&
    (scope === 'organization' ? identity.namespace === null : identity.namespace !== null)
  ) {
    throw new PluginProtocolError(`${path}.namespace 与 scope 不一致`);
  }
  return identity;
}

function parseVisiblePluginBase(
  value: unknown,
  path: string,
): {
  raw: Record<string, unknown>;
  id: string;
  ghostId: string;
  name: string;
  description: string | null;
  author: string | null;
  /** Full workflow-owned nickname; omitted by older servers. */
  displayAuthor?: string | null;
  /** Derived from the verified public authorship binding; not a new database column. */
  publisherKind?: 'official' | 'personal' | null;
  scope: PluginScope;
  namespace?: string | null;
  organizationId: string | null;
  defaultInstall: boolean;
} {
  const raw = object(value, path);
  if (!isValidPluginResourceId(raw.id)) throw new PluginProtocolError(`${path}.id 不合法`);
  if (!isValidGhostId(raw.ghostId)) throw new PluginProtocolError(`${path}.ghostId 不合法`);
  const scope = parseScope(raw.scope, path);
  if (raw.publisherKind !== undefined && raw.publisherKind !== null
    && (scope !== 'public' || (raw.publisherKind !== 'official' && raw.publisherKind !== 'personal'))) {
    throw new PluginProtocolError(`${path}.publisherKind 不合法`);
  }
  const organizationId = parseScopedOrganizationId(scope, raw.organizationId, path);
  const identity = parseScopedNamespace(raw, scope, path);
  if (typeof raw.defaultInstall !== 'boolean') {
    throw new PluginProtocolError(`${path}.defaultInstall 必须是 boolean`);
  }
  return {
    raw,
    id: raw.id,
    ghostId: raw.ghostId,
    name: string(raw.name, `${path}.name`),
    description:
      raw.description === null ? null : string(raw.description, `${path}.description`, 300),
    author: raw.author === null ? null : string(raw.author, `${path}.author`),
    ...(raw.displayAuthor === undefined ? {} : { displayAuthor: raw.displayAuthor === null ? null : string(raw.displayAuthor, `${path}.displayAuthor`, 100) }),
    ...(raw.publisherKind === undefined ? {} : { publisherKind: raw.publisherKind as 'official' | 'personal' | null }),
    scope,
    ...identity,
    organizationId,
    defaultInstall: raw.defaultInstall,
  };
}

function parseVisiblePluginSummary(value: unknown, index: number, options?: PluginObjectUrlOptions): VisiblePluginSummary {
  const path = `plugins[${index}]`;
  const { raw, ...base } = parseVisiblePluginBase(value, path);
  const downloadStatistics = parsePluginDownloadStatistics(raw.downloadStatistics);
  return {
    ...base,
    ...(parsePluginUsageStatistics(raw.usageStatistics) ? { usageStatistics: parsePluginUsageStatistics(raw.usageStatistics) } : {}),
    ...(downloadStatistics ? { downloadStatistics } : {}),
    currentRelease: parseReleaseSummary(raw.currentRelease, `${path}.currentRelease`, options),
  };
}

function parseVisiblePluginDetail(value: unknown, path: string, options?: PluginObjectUrlOptions): VisiblePluginDetail {
  const { raw, ...parsed } = parseVisiblePluginBase(value, path);
  const downloadStatistics = parsePluginDownloadStatistics(raw.downloadStatistics);
  const currentRelease = parseReleaseDetail(
    raw.currentRelease,
    parsed.ghostId,
    `${path}.currentRelease`,
    options,
  );
  if (ghostManifestUsesOidcToken(currentRelease.manifest) && parsed.scope !== 'organization') {
    throw new PluginProtocolError(
      `${path}.currentRelease.manifest 的 oidc-token 仅允许 organization scope`,
    );
  }
  if (parsed.namespace !== currentRelease.manifest.namespace) {
    throw new PluginProtocolError(`${path}.namespace 与有效 manifest 不一致`);
  }
  const manifestDescription = currentRelease.manifest.description ?? null;
  const manifestAuthor = currentRelease.manifest.author ?? null;
  if (parsed.name !== currentRelease.manifest.name) {
    throw new PluginProtocolError(`${path}.name 与 currentRelease.manifest.name 不一致`);
  }
  if (parsed.description !== manifestDescription) {
    throw new PluginProtocolError(
      `${path}.description 与 currentRelease.manifest.description 不一致`,
    );
  }
  if (parsed.author !== manifestAuthor) {
    throw new PluginProtocolError(`${path}.author 与 currentRelease.manifest.author 不一致`);
  }
  return {
    ...parsed,
    ...(parsePluginUsageStatistics(raw.usageStatistics) ? { usageStatistics: parsePluginUsageStatistics(raw.usageStatistics) } : {}),
    ...(downloadStatistics ? { downloadStatistics } : {}),
    currentRelease,
  };
}

function parseRemovalNotice(value: unknown, path: string): PluginRemovalNotice | null {
  const raw = object(value, path);
  if (!isValidPluginResourceId(raw.pluginId)) {
    throw new PluginProtocolError(`${path}.pluginId 不合法`);
  }
  if (!isValidGhostId(raw.ghostId)) throw new PluginProtocolError(`${path}.ghostId 不合法`);
  const scope = parseScope(raw.scope, path);
  const organizationId = parseScopedOrganizationId(scope, raw.organizationId, path);
  const identity = parseScopedNamespace(raw, scope, path);
  const action = string(raw.action, `${path}.action`, 64);
  const removedAt = isoDate(raw.removedAt, `${path}.removedAt`);
  // 未知动作是未来扩展位:结构校验通过后跳过该条而不是拒绝整个响应,
  // 这样服务端新增动作不会打挂旧客户端的整轮列表解析。
  if (!(PLUGIN_REMOVAL_ACTIONS as readonly string[]).includes(action)) return null;
  return {
    pluginId: raw.pluginId,
    ghostId: raw.ghostId,
    scope,
    ...identity,
    organizationId,
    action: action as PluginRemovalAction,
    removedAt,
  };
}

function parseRemovals(value: unknown): PluginRemovalNotice[] {
  // 老的 v2 服务端或未携带通告的身份不带该字段;缺失时规范化为空数组。
  if (value === null || value === undefined) return [];
  if (!Array.isArray(value)) throw new PluginProtocolError('response.removals 必须是数组');
  const notices: PluginRemovalNotice[] = [];
  value.forEach((entry, index) => {
    const notice = parseRemovalNotice(entry, `removals[${index}]`);
    if (notice) notices.push(notice);
  });
  return notices;
}

function parseCurrentOrganization(value: unknown): PluginCurrentOrganization | null {
  // 匿名 / token 降级 / Personal,以及老服务端整段缺失:规范化为 null。
  if (value === null || value === undefined) return null;
  const raw = object(value, 'response.currentOrganization');
  const organizationId = string(
    raw.organizationId,
    'response.currentOrganization.organizationId',
    128,
  );
  const orgSlug =
    Object.prototype.hasOwnProperty.call(raw, 'orgSlug')
      ? { orgSlug: raw.orgSlug as string }
      : {};
  if ('orgSlug' in orgSlug && !isValidPluginNamespace(orgSlug.orgSlug)) {
    throw new PluginProtocolError('currentOrganization.orgSlug 不合法');
  }
  // 「对象在、但省略了 pluginPrefix key」是畸形响应,不能规范化成 null:
  // 那会把「未登记前缀」和「取不到组织」混成一种,上层再也分不开。
  if (!Object.prototype.hasOwnProperty.call(raw, 'pluginPrefix')) {
    throw new PluginProtocolError('response.currentOrganization.pluginPrefix 缺失');
  }
  if (raw.pluginPrefix === null) {
    return { organizationId, ...orgSlug, pluginPrefix: null };
  }
  if (typeof raw.pluginPrefix !== 'string' || !PLUGIN_PREFIX_PATTERN.test(raw.pluginPrefix)) {
    throw new PluginProtocolError('response.currentOrganization.pluginPrefix 不合法');
  }
  return { organizationId, ...orgSlug, pluginPrefix: raw.pluginPrefix };
}

/**
 * 解析并规范化 Plugin 分页列表响应。
 *
 * 未知字段会被忽略;已知字段缺失、值不合法或 schema 版本不支持时抛出
 * `PluginProtocolError`。`removals` 缺失时规范化为空数组,动作未知的通告
 * 会被跳过而不影响其余内容。`currentOrganization` 缺失或为 null 时规范化为
 * `null`;对象存在但缺少 `pluginPrefix` 键时抛错。`organizationAccessError`
 * 缺失时不保留;出现时必须同时有组织身份,且不能夹带企业条目或清理通告。
 */
export function parseListPluginsResponse(value: unknown, options?: PluginObjectUrlOptions): ListPluginsResponse {
  const raw = object(value, 'response');
  if (raw.schemaVersion !== PLUGIN_API_SCHEMA_VERSION) {
    throw new PluginProtocolError(`response.schemaVersion 必须为 ${PLUGIN_API_SCHEMA_VERSION}`);
  }
  if (!Array.isArray(raw.plugins)) throw new PluginProtocolError('response.plugins 必须是数组');
  const plugins = raw.plugins.map((plugin, index) => parseVisiblePluginSummary(plugin, index, options));
  const removals = parseRemovals(raw.removals);
  const currentOrganization = parseCurrentOrganization(raw.currentOrganization);
  const organizationAccessError = parseOrganizationAccessError(raw.organizationAccessError);
  if (
    organizationAccessError &&
    (!currentOrganization ||
      plugins.some((item) => item.scope === 'organization') ||
      removals.length > 0)
  ) {
    throw new PluginProtocolError('企业准入拒绝响应不能包含企业资源或清理通告');
  }
  assertPluginListOrganizationNamespace(currentOrganization, plugins, removals);
  return {
    schemaVersion: PLUGIN_API_SCHEMA_VERSION,
    plugins,
    nextCursor: nextCursor(raw.nextCursor, 'response.nextCursor'),
    removals,
    currentOrganization,
    ...(organizationAccessError ? { organizationAccessError } : {}),
  };
}

const ORGANIZATION_PLUGIN_ACCESS_ERROR_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;

function parseOrganizationAccessError(value: unknown): OrganizationPluginAccessError | undefined {
  if (value === undefined) return undefined;
  const error = object(value, 'response.organizationAccessError');
  const code = string(error.code, 'response.organizationAccessError.code', 64);
  if (!ORGANIZATION_PLUGIN_ACCESS_ERROR_CODE_PATTERN.test(code)) {
    throw new PluginProtocolError('organizationAccessError.code 不合法');
  }
  return {
    code,
    message: string(error.message, 'response.organizationAccessError.message', 512),
  };
}

export function assertPluginListOrganizationNamespace(
  currentOrganization: PluginCurrentOrganization | null,
  plugins: readonly VisiblePluginSummary[],
  removals: readonly PluginRemovalNotice[],
): void {
  if (currentOrganization?.orgSlug !== undefined) {
    for (const item of [...plugins, ...removals]) {
      if (item.scope !== 'organization') continue;
      if (
        item.namespace === undefined ||
        item.organizationId !== currentOrganization.organizationId ||
        item.namespace !== currentOrganization.orgSlug
      ) {
        throw new PluginProtocolError('response 企业 namespace 与 currentOrganization 不一致');
      }
    }
  }
}

/**
 * 解析并规范化单个 Plugin 详情响应。
 *
 * 除通用字段校验外,还要求 manifest 的 id、version 和展示字段与外层数据一致。
 * 校验失败时抛出 `PluginProtocolError`。
 */
export function parseGetPluginResponse(value: unknown, options?: PluginObjectUrlOptions): GetPluginResponse {
  const raw = object(value, 'response');
  if (raw.schemaVersion !== PLUGIN_API_SCHEMA_VERSION) {
    throw new PluginProtocolError(`response.schemaVersion 必须为 ${PLUGIN_API_SCHEMA_VERSION}`);
  }
  return {
    schemaVersion: PLUGIN_API_SCHEMA_VERSION,
    plugin: parseVisiblePluginDetail(raw.plugin, 'response.plugin', options),
  };
}

/**
 * 解析并规范化当前 Release 的短期下载凭证。
 *
 * 默认只接受 HTTPS URL;Host 可显式启用受限本地开发对象地址。UTC 时间、SHA-256 和大小仍严格校验;失败时抛出
 * `PluginProtocolError`。
 */
export function parsePluginDownloadResponse(value: unknown, options?: PluginObjectUrlOptions): PluginDownloadResponse {
  const raw = object(value, 'response');
  if (
    typeof raw.sizeBytes !== 'number' ||
    !Number.isSafeInteger(raw.sizeBytes) ||
    raw.sizeBytes <= 0
  ) {
    throw new PluginProtocolError('response.sizeBytes 必须是正整数');
  }
  const identity = parseOptionalNamespace(raw, 'response');
  const hasIdentity = ['pluginId', 'releaseId', 'ghostId', 'namespace'].some((key) =>
    Object.prototype.hasOwnProperty.call(raw, key),
  );
  if (
    hasIdentity &&
    (!isValidPluginResourceId(raw.pluginId) ||
      !isValidGhostId(raw.ghostId) ||
      !('namespace' in identity))
  ) {
    throw new PluginProtocolError('response 下载身份不完整或不合法');
  }
  return {
    ...(hasIdentity
      ? {
          pluginId: raw.pluginId as string,
          releaseId: string(raw.releaseId, 'response.releaseId', 128),
          ghostId: raw.ghostId as string,
          ...identity,
        }
      : {}),
    url: parsePluginObjectUrl(raw.url, 'response.url', options),
    expiresAt: isoDate(raw.expiresAt, 'response.expiresAt'),
    sha256: sha256(raw.sha256, 'response.sha256'),
    sizeBytes: raw.sizeBytes,
  };
}