@funyard-org/cli 0.0.0-stage → 0.6.3

package/src/protocol/index.js

@@ -0,0 +1,843 @@
+const str = { type: 'string' };
+const integer = { type: 'integer' };
+const nonnegative = { type: 'integer', minimum: 0 };
+const bool = { type: 'boolean' };
+const points = { const: 'test_point' };
+export const requestIdSchema = {
+    type: 'string',
+    pattern: '^[a-z0-9][a-z0-9_-]{0,63}$',
+    maxLength: 64,
+    description: 'Save this stable business ID before submitting. After a timeout use get_call with the same ID; never replace it to retry.',
+};
+export const callIdSchema = { type: 'string', pattern: '^call_[A-Za-z0-9_-]{1,64}$' };
+export const REQUEST_ID = new RegExp(requestIdSchema.pattern);
+export const CALL_ID = new RegExp(callIdSchema.pattern);
+export const CAPABILITY_IDS = [
+    'finance.quote',
+    'web.search',
+    'news.search',
+    'web.read',
+    'company.discover',
+    'research.search',
+    'finance.get',
+    'crypto.get',
+    'economy.get',
+    'tiktok.get',
+    'instagram.get',
+    'youtube.get',
+    'linkedin.get',
+    'social.trending',
+    'news.get',
+];
+/** Canonical field id: category.group.name. The group is the public billing unit. */
+export const FIELD_ID = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*){2}$/;
+/** Field-level capabilities: the argument naming the subject, and the field category they serve. */
+export const FIELD_CAPABILITIES = {
+    'finance.get': { subject: 'symbol', category: 'finance' },
+    'crypto.get': { subject: 'coin', category: 'crypto' },
+    'economy.get': { subject: 'series', category: 'economy' },
+    'tiktok.get': { subject: 'handle', category: 'tiktok' },
+    'instagram.get': { subject: 'handle', category: 'instagram' },
+    'youtube.get': { subject: 'handle', category: 'youtube' },
+    'linkedin.get': { subject: 'company', category: 'linkedin' },
+    'news.get': { subject: 'symbols', category: 'news' },
+};
+export function fieldCapability(id) {
+    return Object.hasOwn(FIELD_CAPABILITIES, id) ? FIELD_CAPABILITIES[id] : undefined;
+}
+export const ARGUMENT_DESCRIPTIONS = {
+    sources: '可选 all：获取全部可用来源，每个来源分别按字段组扣费；省略时只按最低上游成本取数。先用 fields-quote 估价。',
+    symbol: '股票代码，例如 AAPL；会自动去掉首尾空格并转为大写。',
+    coin: '加密货币 ID，例如 bitcoin、ethereum、usd-coin；会自动转为小写。',
+    series: '经济指标序列 ID，例如 UNRATE（美国失业率）、CPIAUCSL（美国 CPI）；会自动转为大写。',
+    handle: '公开账号的用户名，例如 natgeo；可带开头的 @，会自动去掉并转为小写。',
+    platform: '热榜所在平台，目前支持 weibo（微博热搜）。',
+    symbols: '股票代码，逗号分隔，例如 AAPL,MSFT。',
+    company: 'LinkedIn 公司主页的标识，例如 stripe，或完整链接 https://www.linkedin.com/company/stripe/。',
+    fields: '要获取的字段 ID，逗号分隔，例如 finance.quote.price,finance.company.ceo。可用字段和每个字段组的计费标准见 /funyard/v1/fields 目录；同一字段组内取多少字段都只按该组计一次。',
+    query: '要搜索的关键词或问题。',
+    language: '搜索语言代码，例如 en；不传则使用默认语言。',
+    region: '搜索地区代码，例如 us；不传则使用默认地区。',
+    domain: '企业网站域名，例如 example.com，不含协议、端口或路径。',
+    url: '要读取的完整 HTTPS 网址；网站须在允许访问的范围内。',
+};
+export const argumentFields = {
+    sources: { type: 'string', enum: ['all'], minLength: 3, maxLength: 3, description: ARGUMENT_DESCRIPTIONS.sources },
+    symbol: { type: 'string', maxLength: 32, description: ARGUMENT_DESCRIPTIONS.symbol },
+    coin: { type: 'string', maxLength: 100, description: ARGUMENT_DESCRIPTIONS.coin },
+    series: { type: 'string', maxLength: 64, description: ARGUMENT_DESCRIPTIONS.series },
+    handle: { type: 'string', maxLength: 101, description: ARGUMENT_DESCRIPTIONS.handle },
+    company: { type: 'string', maxLength: 200, description: ARGUMENT_DESCRIPTIONS.company },
+    symbols: { type: 'string', maxLength: 500, description: ARGUMENT_DESCRIPTIONS.symbols },
+    platform: { type: 'string', enum: ['weibo'], description: ARGUMENT_DESCRIPTIONS.platform },
+    fields: { type: 'string', minLength: 1, maxLength: 2048, description: ARGUMENT_DESCRIPTIONS.fields },
+    query: { type: 'string', minLength: 1, maxLength: 1024, description: ARGUMENT_DESCRIPTIONS.query },
+    domain: { type: 'string', maxLength: 253, description: ARGUMENT_DESCRIPTIONS.domain },
+    url: { type: 'string', format: 'uri', maxLength: 2048, description: ARGUMENT_DESCRIPTIONS.url },
+    language: {
+        type: 'string',
+        enum: ['en', 'en-us', 'en-gb', 'zh-cn', 'zh-tw', 'ja', 'ko', 'de', 'fr', 'es', 'it', 'pt', 'ru', 'ar'],
+        description: ARGUMENT_DESCRIPTIONS.language,
+    },
+    region: {
+        type: 'string',
+        enum: ['us', 'gb', 'ca', 'au', 'de', 'fr', 'es', 'it', 'jp', 'kr', 'tw', 'hk', 'cn', 'sg', 'in', 'br', 'mx'],
+        description: ARGUMENT_DESCRIPTIONS.region,
+    },
+};
+export const capabilityArguments = {
+    'finance.quote': { required: ['symbol'], optional: [] },
+    'web.search': { required: ['query'], optional: ['language', 'region'] },
+    'news.search': { required: ['query'], optional: ['language', 'region'] },
+    'web.read': { required: ['url'], optional: [] },
+    'company.discover': { required: ['domain'], optional: [] },
+    'research.search': { required: ['query'], optional: ['language'] },
+    'finance.get': { required: ['fields'], optional: ['symbol', 'sources'] },
+    'crypto.get': { required: ['fields'], optional: ['coin', 'sources'] },
+    'economy.get': { required: ['fields'], optional: ['series', 'sources'] },
+    'tiktok.get': { required: ['fields'], optional: ['handle', 'sources'] },
+    'instagram.get': { required: ['fields'], optional: ['handle', 'sources'] },
+    'youtube.get': { required: ['fields'], optional: ['handle', 'sources'] },
+    'linkedin.get': { required: ['fields'], optional: ['company', 'sources'] },
+    'social.trending': { required: ['platform'], optional: [] },
+    'news.get': { required: ['fields'], optional: ['symbols', 'sources'] },
+};
+/** Route policy may narrow fields; it never adds an independently maintained schema. */
+export function capabilityInputSchema(id, internalSearch = false) {
+    const spec = capabilityArguments[id], required = [...spec.required], optional = spec.optional.filter(name => !(internalSearch && name === 'region'));
+    return {
+        type: 'object',
+        properties: Object.fromEntries([...required, ...optional].map(name => [
+            name,
+            internalSearch && name === 'language'
+                ? { type: 'string', maxLength: 8, description: ARGUMENT_DESCRIPTIONS.language }
+                : argumentFields[name],
+        ])),
+        required,
+        additionalProperties: false,
+    };
+}
+export function mcpInputSchema(input) {
+    return {
+        ...input,
+        properties: { ...input.properties, request_id: requestIdSchema },
+        required: [...(input.required ?? []), 'request_id'],
+    };
+}
+export const lookupSchema = {
+    type: 'object',
+    properties: { call_id: callIdSchema, request_id: requestIdSchema },
+    additionalProperties: false,
+    oneOf: [{ required: ['call_id'] }, { required: ['request_id'] }],
+};
+export const cancelSchema = {
+    type: 'object',
+    properties: { call_id: callIdSchema },
+    required: ['call_id'],
+    additionalProperties: false,
+};
+export const emptySchema = { type: 'object', properties: {}, additionalProperties: false };
+/** MCP/SDK inputs for field discovery and dry-run pricing. */
+export const fieldsLookupSchema = {
+    type: 'object',
+    properties: { category: { type: 'string', minLength: 1, maxLength: 32 } },
+    additionalProperties: false,
+};
+const exploreTerm = {
+    type: 'string',
+    minLength: 1,
+    maxLength: 100,
+    pattern: '^[^&#?=%/\\\\\\u0000-\\u001f]+$',
+};
+/** Generic call for arguments a capability's published schema leaves out; the server validates them. */
+export const genericCallRequestSchema = {
+    type: 'object',
+    properties: {
+        capability: { type: 'string', pattern: '^[a-z][a-z0-9_]{0,31}\\.[a-z][a-z0-9_]{0,31}$' },
+        arguments: { type: 'object', additionalProperties: { type: 'string', maxLength: 2048 } },
+        request_id: requestIdSchema,
+    },
+    required: ['capability', 'arguments', 'request_id'],
+    additionalProperties: false,
+};
+/** At most one of these per request: the level to open, or a keyword to search. */
+export const exploreRequestSchema = {
+    type: 'object',
+    properties: { domain: exploreTerm, capability: exploreTerm, group: exploreTerm, q: exploreTerm },
+    additionalProperties: false,
+};
+export const fieldsQuoteRequestSchema = {
+    type: 'object',
+    properties: {
+        fields: { type: 'string', minLength: 1, maxLength: 2048 },
+        sources: { const: 'all' },
+        capability: { type: 'string', pattern: '^[a-z][a-z0-9_]{0,31}\\.[a-z][a-z0-9_]{0,31}$' },
+        arguments: { type: 'object', additionalProperties: { type: 'string', maxLength: 200 } },
+    },
+    required: ['fields'],
+    additionalProperties: false,
+};
+export const submissionSchema = {
+    type: 'object',
+    properties: {
+        request_id: requestIdSchema,
+        capability: str,
+        arguments: { type: 'object', additionalProperties: str },
+    },
+    required: ['request_id', 'capability', 'arguments'],
+    additionalProperties: false,
+};
+export const callIdentitySchema = {
+    type: 'object',
+    properties: {
+        call_id: callIdSchema,
+        request_id: requestIdSchema,
+        capability: str,
+        status: { enum: ['queued', 'running', 'pending', 'succeeded', 'empty', 'failed'] },
+    },
+    required: ['call_id', 'request_id', 'status'],
+};
+const balanceSchema = {
+    type: 'object',
+    properties: { available: nonnegative, held: nonnegative, spent: nonnegative },
+    required: ['available', 'held', 'spent'],
+};
+const errorDetail = {
+    type: 'object',
+    properties: { code: str, message: str, retry_at: nonnegative, cause_code: str },
+    required: ['code', 'message'],
+};
+const nil = { type: 'null' };
+const timestamp = { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$' };
+const resultUrl = { type: 'string', format: 'uri', maxLength: 4096 };
+export const quoteResultSchema = {
+    type: 'object',
+    properties: {
+        symbol: { type: 'string', pattern: '^\\^?[A-Z0-9][A-Z0-9.=-]{0,30}$' },
+        name: { type: 'string', maxLength: 500 },
+        price: { type: 'string', pattern: '^(?:0|[1-9]\\d{0,42})(?:\\.\\d{1,36})?$' },
+        currency: nil,
+        exchange: { type: 'string', maxLength: 100 },
+        data_time: { oneOf: [timestamp, nil] },
+    },
+    required: ['symbol', 'name', 'price', 'currency', 'exchange', 'data_time'],
+    additionalProperties: false,
+};
+export const searchItemSchema = {
+    type: 'object',
+    properties: {
+        title: { type: 'string', maxLength: 512 },
+        url: resultUrl,
+        snippet: { type: 'string', maxLength: 4096 },
+        source: { type: 'string', maxLength: 256 },
+        published_at: timestamp,
+    },
+    required: ['title', 'url', 'snippet'],
+    additionalProperties: false,
+};
+export const searchResultSchema = {
+    type: 'object',
+    properties: {
+        items: { type: 'array', items: searchItemSchema, minItems: 1, maxItems: 10 },
+        omitted_links: { type: 'integer', minimum: 1 },
+    },
+    required: ['items'],
+    additionalProperties: false,
+};
+/** One trending topic: its rank on the list, the search link, and the platform's own heat score. */
+export const trendingItemSchema = {
+    type: 'object',
+    properties: {
+        rank: { type: 'integer', minimum: 1, maximum: 100 },
+        title: { type: 'string', minLength: 1, maxLength: 512 },
+        url: resultUrl,
+        heat: { oneOf: [nonnegative, nil] },
+        label: { oneOf: [{ type: 'string', maxLength: 32 }, nil] },
+    },
+    required: ['rank', 'title', 'url', 'heat', 'label'],
+    additionalProperties: false,
+};
+export const trendingResultSchema = {
+    type: 'object',
+    properties: { items: { type: 'array', items: trendingItemSchema, minItems: 1, maxItems: 50 } },
+    required: ['items'],
+    additionalProperties: false,
+};
+export const readResultSchema = {
+    type: 'object',
+    properties: {
+        url: resultUrl,
+        title: { type: 'string', maxLength: 1000 },
+        markdown: { type: 'string', maxLength: 49152, pattern: '\\S' },
+        omitted_links: nonnegative,
+    },
+    required: ['url', 'title', 'markdown', 'omitted_links'],
+    additionalProperties: false,
+};
+const nullableCount = { oneOf: [nonnegative, nil] };
+export const companyItemSchema = {
+    type: 'object',
+    properties: {
+        domain: { type: 'string', maxLength: 253 },
+        company_name: { type: 'string', minLength: 1, maxLength: 500 },
+        email_counts: {
+            oneOf: [
+                {
+                    type: 'object',
+                    properties: { personal: nullableCount, generic: nullableCount, total: nullableCount },
+                    required: ['personal', 'generic', 'total'],
+                    additionalProperties: false,
+                },
+                nil,
+            ],
+        },
+    },
+    required: ['domain', 'company_name', 'email_counts'],
+    additionalProperties: false,
+};
+export const companyResultSchema = {
+    type: 'object',
+    properties: { items: { type: 'array', items: companyItemSchema, minItems: 1, maxItems: 1 } },
+    required: ['items'],
+    additionalProperties: false,
+};
+/** Field-level outcome. A group is charged only when every requested field in it is succeeded or empty. */
+export const fieldStatusSchema = { enum: ['succeeded', 'empty', 'pending', 'failed'] };
+const fieldScalar = { oneOf: [str, { type: 'number' }, bool, nil] };
+/** A scalar, or a column of scalars: fields of a list-shaped group (statements, histories, posts)
+ * hold one value per row, and every field of that group lists its rows in the same order. */
+export const fieldValueSchema = {
+    oneOf: [str, { type: 'number' }, bool, nil, { type: 'array', maxItems: 1000, items: fieldScalar }],
+};
+/** With sources=all, each source's own outcome under an anonymous label that is stable per source. */
+const fieldSourceSchema = {
+    type: 'object',
+    properties: {
+        source: { type: 'string', pattern: '^s[1-9][0-9]?$' },
+        status: fieldStatusSchema,
+        value: fieldValueSchema,
+    },
+    required: ['source', 'status', 'value'],
+    additionalProperties: false,
+};
+const fieldsMap = {
+    type: 'object',
+    additionalProperties: {
+        type: 'object',
+        properties: {
+            status: fieldStatusSchema,
+            value: fieldValueSchema,
+            sources: { type: 'array', minItems: 1, maxItems: 20, items: fieldSourceSchema },
+        },
+        required: ['status', 'value'],
+        additionalProperties: false,
+    },
+};
+export const fieldsResultSchema = {
+    type: 'object',
+    properties: { symbol: quoteResultSchema.properties.symbol, fields: fieldsMap },
+    required: ['fields'],
+    // Echo of every argument the request carried.
+    additionalProperties: { type: 'string', maxLength: 200 },
+};
+export const cryptoFieldsResultSchema = {
+    type: 'object',
+    properties: { coin: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,99}$' }, fields: fieldsMap },
+    required: ['fields'],
+    // Echo of every argument the request carried.
+    additionalProperties: { type: 'string', maxLength: 200 },
+};
+export const economyFieldsResultSchema = {
+    type: 'object',
+    properties: { series: { type: 'string', pattern: '^[A-Z0-9][A-Z0-9_]{0,63}$' }, fields: fieldsMap },
+    required: ['fields'],
+    // Echo of every argument the request carried.
+    additionalProperties: { type: 'string', maxLength: 200 },
+};
+export const socialFieldsResultSchema = {
+    type: 'object',
+    properties: { handle: { type: 'string', pattern: '^[a-z0-9_][a-z0-9._-]{0,99}$' }, fields: fieldsMap },
+    required: ['fields'],
+    // Echo of every argument the request carried.
+    additionalProperties: { type: 'string', maxLength: 200 },
+};
+/** Field results whose capability has no normalized subject: the field map plus echoed arguments. */
+export const echoFieldsResultSchema = {
+    type: 'object',
+    properties: { fields: fieldsMap },
+    required: ['fields'],
+    additionalProperties: { type: 'string', maxLength: 500 },
+};
+export const linkedinFieldsResultSchema = {
+    type: 'object',
+    properties: { company: { type: 'string', pattern: '^[a-z0-9][a-z0-9_-]{0,99}$' }, fields: fieldsMap },
+    required: ['fields'],
+    // Echo of every argument the request carried.
+    additionalProperties: { type: 'string', maxLength: 200 },
+};
+export const resultSchemas = {
+    'finance.quote': quoteResultSchema,
+    'web.search': searchResultSchema,
+    'news.search': searchResultSchema,
+    'research.search': searchResultSchema,
+    'web.read': readResultSchema,
+    'company.discover': companyResultSchema,
+    'finance.get': fieldsResultSchema,
+    'crypto.get': cryptoFieldsResultSchema,
+    'economy.get': economyFieldsResultSchema,
+    'tiktok.get': socialFieldsResultSchema,
+    'instagram.get': socialFieldsResultSchema,
+    'youtube.get': socialFieldsResultSchema,
+    'linkedin.get': linkedinFieldsResultSchema,
+    'social.trending': trendingResultSchema,
+    'news.get': echoFieldsResultSchema,
+};
+const emptyItems = {
+    type: 'object',
+    properties: { items: { type: 'array', items: {}, maxItems: 0 } },
+    required: ['items'],
+    additionalProperties: false,
+};
+export const emptyResultSchemas = {
+    'finance.quote': nil,
+    'web.search': emptyItems,
+    'news.search': emptyItems,
+    'research.search': emptyItems,
+    'company.discover': emptyItems,
+    'social.trending': emptyItems,
+    'web.read': {
+        ...readResultSchema,
+        properties: { ...readResultSchema.properties, markdown: { type: 'string', maxLength: 49152, pattern: '^\\s*$' } },
+    },
+    'finance.get': fieldsResultSchema,
+    'crypto.get': cryptoFieldsResultSchema,
+    'economy.get': economyFieldsResultSchema,
+    'tiktok.get': socialFieldsResultSchema,
+    'instagram.get': socialFieldsResultSchema,
+    'youtube.get': socialFieldsResultSchema,
+    'linkedin.get': linkedinFieldsResultSchema,
+    'news.get': echoFieldsResultSchema,
+};
+/** Only field-level capabilities deliver confirmed fields while others are still pending. */
+export const PARTIAL_RESULT_CAPABILITIES = Object.keys(FIELD_CAPABILITIES);
+/** Shape shared by every field-level result: the field map plus an echo of the request's arguments. Lets a client
+ * accept field capabilities the server added after it was built, without trusting arbitrary data. */
+export function fieldsResultMatches(status, value) {
+    if (value === null)
+        return ['queued', 'running', 'pending', 'failed'].includes(status);
+    if (!['succeeded', 'empty', 'pending'].includes(status) || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value, echoed = Object.keys(record).filter(key => key !== 'fields');
+    return (echoed.length <= 16 &&
+        echoed.every(key => /^[a-z][a-z0-9_]{0,31}$/.test(key) && typeof record[key] === 'string' && record[key].length <= 200) &&
+        matches(fieldsMap, record.fields));
+}
+export function resultMatches(capability, status, value) {
+    if (!Object.hasOwn(resultSchemas, capability))
+        return false;
+    if (status === 'succeeded')
+        return matches(resultSchemas[capability], value);
+    if (status === 'empty')
+        return matches(emptyResultSchemas[capability], value);
+    if (status === 'pending' && PARTIAL_RESULT_CAPABILITIES.includes(capability))
+        return value === null || matches(resultSchemas[capability], value);
+    return ['queued', 'running', 'pending', 'failed'].includes(status) && value === null;
+}
+export const billingLineSchema = {
+    type: 'object',
+    properties: {
+        group: str,
+        source: { type: 'string', pattern: '^s[1-9][0-9]?$' },
+        title: str,
+        weight: nonnegative,
+        fields: { type: 'array', items: str },
+        status: { enum: ['queued', 'running', 'pending', 'succeeded', 'empty', 'failed'] },
+        charged: nonnegative,
+        settled_at: nonnegative,
+    },
+    required: ['group', 'weight', 'fields', 'status', 'charged'],
+};
+export const callEnvelopeSchema = {
+    type: 'object',
+    properties: {
+        ...callIdentitySchema.properties,
+        capability_version: { const: 1 },
+        replayed: bool,
+        created_at: nonnegative,
+        idempotency_expires_at: nonnegative,
+        trace_id: str,
+        source: { type: 'object', properties: { requested_at: nonnegative, fetched_at: str }, required: ['requested_at'] },
+        billing: {
+            type: 'object',
+            properties: {
+                unit: points,
+                rate_version: str,
+                price: nonnegative,
+                held: nonnegative,
+                charged: nonnegative,
+                balance_snapshot: balanceSchema,
+                /** One line per field group; present for field-level capabilities. */
+                lines: { type: 'array', items: billingLineSchema },
+            },
+            required: ['unit', 'rate_version', 'price', 'held', 'charged', 'balance_snapshot'],
+        },
+        retention_deferred: bool,
+        poll_after_ms: nonnegative,
+        error: errorDetail,
+    },
+    required: [
+        'call_id',
+        'request_id',
+        'capability',
+        'capability_version',
+        'status',
+        'replayed',
+        'created_at',
+        'idempotency_expires_at',
+        'trace_id',
+        'source',
+        'billing',
+    ],
+};
+const resultBranches = CAPABILITY_IDS.flatMap(capability => [
+    {
+        type: 'object',
+        properties: { capability: { const: capability }, status: { const: 'succeeded' }, data: resultSchemas[capability] },
+    },
+    {
+        type: 'object',
+        properties: { capability: { const: capability }, status: { const: 'empty' }, data: emptyResultSchemas[capability] },
+    },
+    ...(PARTIAL_RESULT_CAPABILITIES.includes(capability)
+        ? [
+            {
+                type: 'object',
+                properties: {
+                    capability: { const: capability },
+                    status: { const: 'pending' },
+                    data: { oneOf: [resultSchemas[capability], nil] },
+                },
+            },
+            {
+                type: 'object',
+                properties: {
+                    capability: { const: capability },
+                    status: { enum: ['queued', 'running', 'failed'] },
+                    data: nil,
+                },
+            },
+        ]
+        : [
+            {
+                type: 'object',
+                properties: {
+                    capability: { const: capability },
+                    status: { enum: ['queued', 'running', 'pending', 'failed'] },
+                    data: nil,
+                },
+            },
+        ]),
+]);
+// Summary list deliberately omits data; a full submission/read response must have it.
+export const callSummarySchema = { ...callEnvelopeSchema, oneOf: resultBranches };
+export const callSchema = { ...callSummarySchema, required: [...callEnvelopeSchema.required, 'data'] };
+export const capabilitySchema = {
+    type: 'object',
+    properties: {
+        name: { enum: CAPABILITY_IDS },
+        title: str,
+        description: str,
+        category: str,
+        version: { const: 1 },
+        price: nonnegative,
+        unit: points,
+        /** per_call: price is charged per request. per_field_group: price is the smallest charge; see /fields/quote. */
+        price_model: { enum: ['per_call', 'per_field_group'] },
+        price_description: str,
+        input_schema: { type: 'object' },
+        enabled: bool,
+    },
+    required: ['name', 'title', 'description', 'category', 'version', 'price', 'unit', 'input_schema', 'enabled'],
+};
+export const catalogSchema = {
+    type: 'object',
+    properties: { capabilities: { type: 'array', items: capabilitySchema } },
+    required: ['capabilities'],
+};
+export const accountSchema = {
+    type: 'object',
+    properties: {
+        user_id: nonnegative,
+        enabled: bool,
+        capabilities: str,
+        ...balanceSchema.properties,
+        unit: points,
+        created_at: nonnegative,
+        limits: {
+            type: 'object',
+            properties: {
+                rpm: nonnegative,
+                daily_calls: nonnegative,
+                daily_points: nonnegative,
+                concurrency: nonnegative,
+                queue: nonnegative,
+                held_points: nonnegative,
+            },
+            required: ['rpm', 'daily_calls', 'daily_points', 'concurrency', 'queue', 'held_points'],
+        },
+        preferences: { type: 'object', properties: { language: { enum: ['zh', 'en'] } }, required: ['language'] },
+    },
+    required: [
+        'user_id',
+        'enabled',
+        'capabilities',
+        'available',
+        'held',
+        'spent',
+        'unit',
+        'created_at',
+        'limits',
+        'preferences',
+    ],
+};
+export const meSchema = {
+    type: 'object',
+    properties: { account: accountSchema, key_id: str },
+    required: ['account', 'key_id'],
+};
+export const usageSchema = {
+    type: 'object',
+    properties: {
+        unit: points,
+        entries: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    call_id: str,
+                    kind: str,
+                    available_delta: integer,
+                    held_delta: integer,
+                    spent_delta: integer,
+                    created_at: nonnegative,
+                    /** Field group this settlement belongs to; absent for whole-call settlements. */
+                    line: str,
+                },
+                required: ['call_id', 'kind', 'available_delta', 'held_delta', 'spent_delta', 'created_at'],
+            },
+        },
+    },
+    required: ['unit', 'entries'],
+};
+export const errorSchema = {
+    type: 'object',
+    properties: { error: errorDetail, trace_id: str },
+    required: ['error', 'trace_id'],
+};
+const fieldGroupSchema = {
+    type: 'object',
+    properties: { id: str, category: str, title: str, price: nonnegative, unit: points, rate_version: str },
+    required: ['id', 'category', 'title', 'price', 'unit', 'rate_version'],
+};
+export const fieldDefinitionSchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string', pattern: FIELD_ID.source },
+        group: str,
+        category: str,
+        title: str,
+        type: { enum: ['string', 'number', 'integer', 'boolean', 'decimal', 'timestamp', 'scalar'] },
+        /** Points charged for the whole group when any of its fields is requested. */
+        price: nonnegative,
+        unit: points,
+        rate_version: str,
+        arguments: { type: 'array', items: str },
+        /** Optional arguments its sources forward (period, limit, from...). */
+        options: { type: 'array', items: str },
+        /** Delivered as a column: one value per row, aligned with the other fields of its group. */
+        list: bool,
+    },
+    required: ['id', 'group', 'category', 'title', 'type', 'price', 'unit', 'rate_version', 'arguments'],
+};
+export const fieldsCatalogSchema = {
+    type: 'object',
+    properties: {
+        groups: { type: 'array', items: fieldGroupSchema },
+        fields: { type: 'array', items: fieldDefinitionSchema },
+    },
+    required: ['groups', 'fields'],
+};
+const exploreGroupSchema = {
+    type: 'object',
+    properties: { id: str, title: str, price: nonnegative, fields: nonnegative },
+    required: ['id', 'title', 'price', 'fields'],
+};
+const exploreCapabilitySchema = {
+    type: 'object',
+    properties: {
+        name: str,
+        title: str,
+        description: str,
+        domain: str,
+        /** fields: pick field ids and pay per field group. call: one fixed result per request. */
+        kind: { enum: ['fields', 'call'] },
+        /** Callable now with this key: in its scope and served by an enabled route. */
+        available: bool,
+        price: nonnegative,
+        unit: points,
+        price_model: { enum: ['per_call', 'per_field_group'] },
+        input_schema: { type: 'object' },
+        groups: { type: 'array', items: exploreGroupSchema },
+        example: { type: 'object' },
+    },
+    required: ['name', 'title', 'description', 'domain', 'kind', 'available', 'price', 'unit', 'price_model'],
+};
+/** Progressive discovery: root -> domain -> capability -> group -> fields, or a keyword search. */
+export const exploreSchema = {
+    type: 'object',
+    properties: {
+        level: { enum: ['root', 'domain', 'capability', 'group', 'search'] },
+        domains: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: { id: str, title: str, description: str, capabilities: nonnegative, fields: nonnegative },
+                required: ['id', 'title', 'description', 'capabilities', 'fields'],
+            },
+        },
+        domain: {
+            type: 'object',
+            properties: { id: str, title: str, description: str },
+            required: ['id', 'title', 'description'],
+        },
+        capabilities: { type: 'array', items: exploreCapabilitySchema },
+        capability: exploreCapabilitySchema,
+        group: {
+            type: 'object',
+            properties: {
+                ...exploreGroupSchema.properties,
+                capability: str,
+                unit: points,
+                fields: { type: 'array', items: fieldDefinitionSchema },
+            },
+            required: ['id', 'title', 'price', 'capability', 'unit', 'fields'],
+        },
+        matches: { type: 'array', items: fieldDefinitionSchema },
+        next: str,
+    },
+    required: ['level', 'next'],
+};
+/** Dry-run price for a field list; nothing is reserved or charged. */
+export const fieldsQuoteSchema = {
+    type: 'object',
+    properties: {
+        sources: { const: 'all' },
+        unit: points,
+        rate_version: str,
+        total: nonnegative,
+        lines: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    group: str,
+                    source: { type: 'string', pattern: '^s[1-9][0-9]?$' },
+                    title: str,
+                    weight: nonnegative,
+                    fields: { type: 'array', items: str },
+                },
+                required: ['group', 'weight', 'fields'],
+            },
+        },
+        unknown: { type: 'array', items: str },
+    },
+    required: ['unit', 'rate_version', 'total', 'lines', 'unknown'],
+};
+export const schemas = {
+    submission: submissionSchema,
+    callIdentity: callIdentitySchema,
+    call: callSchema,
+    catalog: catalogSchema,
+    account: accountSchema,
+    me: meSchema,
+    usage: usageSchema,
+    error: errorSchema,
+    lookup: lookupSchema,
+    cancel: cancelSchema,
+    fieldsCatalog: fieldsCatalogSchema,
+    fieldsQuote: fieldsQuoteSchema,
+    explore: exploreSchema,
+};
+/** Validate own data properties only; never invoke getters supplied by SDK callers. */
+export function matches(schema, value) {
+    if (schema.const !== undefined && value !== schema.const)
+        return false;
+    if (schema.enum && !schema.enum.includes(value))
+        return false;
+    if (schema.oneOf && schema.oneOf.filter(part => matches(part, value)).length !== 1)
+        return false;
+    if (schema.type === 'null' && value !== null)
+        return false;
+    if (schema.type === 'string') {
+        if (typeof value !== 'string')
+            return false;
+        if ((schema.minLength !== undefined && [...value].length < schema.minLength) ||
+            (schema.maxLength !== undefined && [...value].length > schema.maxLength) ||
+            (schema.pattern && !new RegExp(schema.pattern).test(value)))
+            return false;
+        if (schema.format === 'uri') {
+            try {
+                new URL(value);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    else if (schema.type === 'boolean' && typeof value !== 'boolean')
+        return false;
+    else if (schema.type === 'integer' || schema.type === 'number') {
+        if (typeof value !== 'number' ||
+            !Number.isFinite(value) ||
+            (schema.type === 'integer' && !Number.isSafeInteger(value)) ||
+            (schema.minimum !== undefined && value < schema.minimum))
+            return false;
+    }
+    else if (schema.type === 'array') {
+        if (!Array.isArray(value) ||
+            (schema.minItems !== undefined && value.length < schema.minItems) ||
+            (schema.maxItems !== undefined && value.length > schema.maxItems) ||
+            (schema.items && !value.every(item => matches(schema.items, item))))
+            return false;
+    }
+    if (schema.type === 'object' || schema.required) {
+        if (!value ||
+            typeof value !== 'object' ||
+            Array.isArray(value) ||
+            ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            return false;
+        if (schema.required?.some(key => !Object.hasOwn(value, key)))
+            return false;
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                return false;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor))
+                return false;
+            const field = schema.properties && Object.hasOwn(schema.properties, key) ? schema.properties[key] : undefined;
+            if ((field && !matches(field, descriptor.value)) || (!field && schema.additionalProperties === false))
+                return false;
+            if (!field &&
+                schema.additionalProperties &&
+                typeof schema.additionalProperties === 'object' &&
+                !matches(schema.additionalProperties, descriptor.value))
+                return false;
+        }
+    }
+    return true;
+}
+export function assertSchema(schema, value) {
+    if (!matches(schema, value))
+        throw new Error('PROTOCOL_CONTRACT_INVALID');
+    return value;
+}