@apifuse/provider-sdk 2.1.0-beta.5 → 2.1.0-beta.8

package/dist/contract-json.d.ts

@@ -0,0 +1,9 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export declare function canonicalJson(value: unknown): string;
+export declare function toJsonValue(value: unknown): JsonValue | undefined;
+export declare function compactObject(value: Record<string, JsonValue | undefined>): JsonValue;
+export declare function copyRecordWithout(value: unknown, ignoredKeys: ReadonlySet<string>): Record<string, unknown>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/contract-json.js

@@ -0,0 +1,51 @@
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(toJsonValue(value) ?? null));
+}
+export function toJsonValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => {
+            const json = toJsonValue(item);
+            return json === undefined ? [] : [json];
+        });
+    }
+    if (!isRecord(value))
+        return undefined;
+    return compactObject(Object.fromEntries(Object.entries(value).flatMap(([key, item]) => {
+        const json = toJsonValue(item);
+        return json === undefined ? [] : [[key, json]];
+    })));
+}
+export function compactObject(value) {
+    return Object.fromEntries(Object.entries(value).filter((entry) => {
+        const [, item] = entry;
+        return item !== undefined;
+    }));
+}
+export function copyRecordWithout(value, ignoredKeys) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !ignoredKeys.has(key)));
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+        .flatMap(([key, item]) => {
+        const json = toJsonValue(item);
+        return json === undefined ? [] : [[key, canonicalize(json)]];
+    }));
+}

package/dist/contract-serialization.d.ts

@@ -0,0 +1,4 @@
+import { type JsonValue } from "./contract-json";
+import type { SchemaLike } from "./types";
+export declare function describeSchema(schema: SchemaLike): JsonValue;
+export declare function serializeSmsMatcher(value: Record<string, unknown>): Record<string, unknown>;

package/dist/contract-serialization.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json";
+export function describeSchema(schema) {
+    if (isZodSchema(schema)) {
+        const jsonSchema = zodJsonSchema(schema);
+        return compactObject({
+            kind: "schema",
+            vendor: "zod",
+            typeName: getSchemaTypeName(schema),
+            jsonSchema,
+            jsonSchemaHash: jsonSchema === undefined
+                ? undefined
+                : digest(canonicalJson(jsonSchema)),
+        });
+    }
+    const standard = isRecord(schema) ? schema["~standard"] : undefined;
+    if (isRecord(standard)) {
+        return compactObject({
+            kind: "schema",
+            standard: "standard-schema-v1",
+            vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
+            version: typeof standard.version === "number" ||
+                typeof standard.version === "string"
+                ? standard.version
+                : undefined,
+        });
+    }
+    return compactObject({
+        kind: "schema",
+        vendor: "zod",
+        typeName: getSchemaTypeName(schema),
+    });
+}
+export function serializeSmsMatcher(value) {
+    const code = value.code;
+    if (!isRecord(code))
+        return value;
+    const pattern = code.pattern;
+    if (!(pattern instanceof RegExp))
+        return value;
+    return {
+        ...value,
+        code: {
+            ...code,
+            pattern: {
+                source: pattern.source,
+                flags: pattern.flags,
+            },
+        },
+    };
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function isZodSchema(schema) {
+    return schema instanceof z.ZodType;
+}
+function zodJsonSchema(schema) {
+    try {
+        const jsonSchema = z.toJSONSchema(schema);
+        return toJsonValue(jsonSchema);
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return undefined;
+        throw error;
+    }
+}
+function getSchemaTypeName(schema) {
+    if (!isRecord(schema))
+        return undefined;
+    const def = schema._def;
+    if (!isRecord(def))
+        return undefined;
+    const typeName = def.typeName ?? def.type;
+    return typeof typeName === "string" ? typeName : undefined;
+}

package/dist/contract-types.d.ts

@@ -0,0 +1,49 @@
+import type { JsonValue } from "./contract-json";
+import type { ProviderDefinition } from "./types";
+export declare const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
+export interface ProviderContractSnapshot {
+    readonly schemaVersion: typeof PROVIDER_CONTRACT_SCHEMA_VERSION;
+    readonly provider: {
+        readonly id: string;
+        readonly version: string;
+        readonly runtime: ProviderDefinition["runtime"];
+    };
+    readonly allowedHosts?: readonly string[];
+    readonly stealth?: JsonValue;
+    readonly proxy?: JsonValue;
+    readonly stt?: JsonValue;
+    readonly browser?: JsonValue;
+    readonly auth?: JsonValue;
+    readonly reviewed?: JsonValue;
+    readonly access?: JsonValue;
+    readonly secrets?: JsonValue;
+    readonly credential?: JsonValue;
+    readonly context?: JsonValue;
+    readonly meta: JsonValue;
+    readonly healthMonitor?: JsonValue;
+    readonly healthJourneys?: readonly JsonValue[];
+    readonly operations: readonly ProviderContractOperation[];
+}
+export interface ProviderContractOperation {
+    readonly id: string;
+    readonly descriptionKey?: JsonValue;
+    readonly docs?: JsonValue;
+    readonly whenToUseKeys?: JsonValue;
+    readonly whenNotToUseKeys?: JsonValue;
+    readonly derivations?: JsonValue;
+    readonly inputExamples?: JsonValue;
+    readonly annotations?: JsonValue;
+    readonly contract?: JsonValue;
+    readonly tags?: JsonValue;
+    readonly relatedOperations?: JsonValue;
+    readonly toolRouter?: JsonValue;
+    readonly observability?: JsonValue;
+    readonly transport?: JsonValue;
+    readonly inputSchema: JsonValue;
+    readonly outputSchema: JsonValue;
+    readonly fixtures?: JsonValue;
+    readonly upstream?: JsonValue;
+    readonly hints?: JsonValue;
+    readonly healthCheck?: JsonValue;
+    readonly healthCheckUnsupported?: JsonValue;
+}

package/dist/contract-types.js

@@ -0,0 +1 @@
+export const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";

package/dist/contract.d.ts

@@ -0,0 +1,6 @@
+import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types";
+import type { ProviderDefinition } from "./types";
+export { canonicalJson, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, };
+export declare function extractProviderContract(provider: ProviderDefinition): ProviderContractSnapshot;
+export declare function digestProviderContract(snapshot: ProviderContractSnapshot): string;

package/dist/contract.js

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types";
+export { canonicalJson, PROVIDER_CONTRACT_SCHEMA_VERSION, };
+export function extractProviderContract(provider) {
+    const auth = extractAuth(provider.auth);
+    const stealth = toJsonValue(provider.stealth);
+    const proxy = toJsonValue(provider.proxy);
+    const stt = toJsonValue(provider.stt);
+    const browser = toJsonValue(provider.browser);
+    const reviewed = toJsonValue(provider.reviewed);
+    const access = toJsonValue(provider.access);
+    const secrets = toJsonValue(provider.secrets);
+    const credential = toJsonValue(provider.credential);
+    const context = toJsonValue(provider.context);
+    const healthMonitor = toJsonValue(provider.healthMonitor);
+    const healthJourneys = provider.healthJourneys?.map(extractHealthJourney);
+    return {
+        schemaVersion: PROVIDER_CONTRACT_SCHEMA_VERSION,
+        provider: {
+            id: provider.id,
+            version: provider.version,
+            runtime: provider.runtime,
+        },
+        meta: toJsonValue(provider.meta) ?? null,
+        operations: Object.entries(provider.operations)
+            .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
+            .map(([operationId, operation]) => extractOperation(operationId, operation)),
+        ...(provider.allowedHosts
+            ? { allowedHosts: [...provider.allowedHosts].sort() }
+            : {}),
+        ...(stealth === undefined ? {} : { stealth }),
+        ...(proxy === undefined ? {} : { proxy }),
+        ...(stt === undefined ? {} : { stt }),
+        ...(browser === undefined ? {} : { browser }),
+        ...(auth === undefined ? {} : { auth }),
+        ...(reviewed === undefined ? {} : { reviewed }),
+        ...(access === undefined ? {} : { access }),
+        ...(secrets === undefined ? {} : { secrets }),
+        ...(credential === undefined ? {} : { credential }),
+        ...(context === undefined ? {} : { context }),
+        ...(healthMonitor === undefined ? {} : { healthMonitor }),
+        ...(healthJourneys === undefined ? {} : { healthJourneys }),
+    };
+}
+export function digestProviderContract(snapshot) {
+    return createHash("sha256").update(canonicalJson(snapshot)).digest("hex");
+}
+function extractOperation(operationId, operation) {
+    const descriptionKey = toJsonValue(operation.descriptionKey);
+    const docs = toJsonValue(operation.docs);
+    const whenToUseKeys = toJsonValue(operation.whenToUseKeys);
+    const whenNotToUseKeys = toJsonValue(operation.whenNotToUseKeys);
+    const derivations = toJsonValue(operation.derivations);
+    const inputExamples = toJsonValue(operation.inputExamples);
+    const annotations = toJsonValue(operation.annotations);
+    const contract = toJsonValue(operation.contract);
+    const tags = toJsonValue(operation.tags);
+    const relatedOperations = toJsonValue(operation.relatedOperations);
+    const toolRouter = toJsonValue(operation.toolRouter);
+    const observability = toJsonValue(operation.observability);
+    const transport = extractTransport(operation.transport);
+    const fixtures = toJsonValue(operation.fixtures);
+    const upstream = toJsonValue(operation.upstream);
+    const hints = toJsonValue(operation.hints);
+    const healthCheck = extractHealthCheck(operation.healthCheck);
+    const healthCheckUnsupported = extractHealthCheckUnsupported(operation.healthCheckUnsupported);
+    return {
+        id: operationId,
+        inputSchema: describeSchema(operation.input),
+        outputSchema: describeSchema(operation.output),
+        ...(descriptionKey === undefined ? {} : { descriptionKey }),
+        ...(docs === undefined ? {} : { docs }),
+        ...(whenToUseKeys === undefined ? {} : { whenToUseKeys }),
+        ...(whenNotToUseKeys === undefined ? {} : { whenNotToUseKeys }),
+        ...(derivations === undefined ? {} : { derivations }),
+        ...(inputExamples === undefined ? {} : { inputExamples }),
+        ...(annotations === undefined ? {} : { annotations }),
+        ...(contract === undefined ? {} : { contract }),
+        ...(tags === undefined ? {} : { tags }),
+        ...(relatedOperations === undefined ? {} : { relatedOperations }),
+        ...(toolRouter === undefined ? {} : { toolRouter }),
+        ...(observability === undefined ? {} : { observability }),
+        ...(transport === undefined ? {} : { transport }),
+        ...(fixtures === undefined ? {} : { fixtures }),
+        ...(upstream === undefined ? {} : { upstream }),
+        ...(hints === undefined ? {} : { hints }),
+        ...(healthCheck === undefined ? {} : { healthCheck }),
+        ...(healthCheckUnsupported === undefined ? {} : { healthCheckUnsupported }),
+    };
+}
+function extractAuth(value) {
+    if (!value)
+        return undefined;
+    return compactObject({
+        mode: value.mode,
+        flow: value.flow
+            ? compactObject({
+                start: true,
+                continue: true,
+                poll: value.flow.poll === undefined ? undefined : true,
+                abort: value.flow.abort === undefined ? undefined : true,
+            })
+            : undefined,
+    });
+}
+function extractTransport(value) {
+    if (!value)
+        return undefined;
+    if (value.kind !== "sse")
+        return toJsonValue(value);
+    return compactObject({
+        ...copyRecordWithout(value, new Set(["events"])),
+        events: Object.fromEntries(Object.entries(value.events)
+            .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
+            .map(([eventName, schema]) => [eventName, describeSchema(schema)])),
+    });
+}
+function extractHealthCheck(value) {
+    if (!value)
+        return undefined;
+    return compactObject({
+        interval: value.interval,
+        timeoutMs: value.timeoutMs,
+        degradedThresholdMs: value.degradedThresholdMs,
+        requiresConnection: value.requiresConnection,
+        cases: value.cases.map((item) => compactObject({
+            name: item.name,
+            description: item.description,
+            input: toJsonValue(item.input),
+            degradedThresholdMs: item.degradedThresholdMs,
+            timeoutMs: item.timeoutMs,
+            expectedStatus: item.expectedStatus,
+        })),
+    });
+}
+function extractHealthCheckUnsupported(value) {
+    return toJsonValue(value);
+}
+function extractHealthJourney(value) {
+    return compactObject({
+        id: value.id,
+        title: value.title,
+        description: value.description,
+        schedule: toJsonValue(value.schedule),
+        coversOperations: toJsonValue(value.coversOperations),
+        timeout: value.timeout,
+        cooldown: value.cooldown,
+        smsMatchers: toJsonValue(value.smsMatchers?.map((matcher) => serializeSmsMatcher(copyRecordWithout(matcher, new Set(["extractOtp"]))))),
+        requiredSecrets: toJsonValue(value.requiredSecrets),
+        manualTrigger: toJsonValue(value.manualTrigger),
+        steps: toJsonValue(value.steps),
+    });
+}

package/dist/define.d.ts

@@ -0,0 +1,97 @@
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
+type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
+type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
+interface ProviderImplementationProfile {
+    sourceAccess: ProviderImplementationSourceAccess;
+    credentialStrategy: ProviderImplementationCredentialStrategy;
+    officialDocsUrl?: string;
+    operatorNotes?: string;
+    visibility: "internal" | "operator";
+}
+type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
+type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationDefinition<TInput, TOutput>, "handler"> & {
+    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
+};
+type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
+    [K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput> ? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput> : never;
+};
+type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = SseOperationConfig<TInput, TOutput> | HttpStreamOperationConfig<TInput, TOutput> | WebSocketOperationConfig<TInput, TOutput>;
+type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationConfig<TInput, TOutput>, "handler" | "transport"> & {
+    transport: OperationSseTransport;
+    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
+};
+type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationConfig<TInput, TOutput>, "handler" | "transport"> & {
+    transport: OperationHttpStreamTransport;
+    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
+};
+type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<OperationConfig<TInput, TOutput>, "handler" | "transport"> & {
+    transport: OperationWebSocketTransport;
+    handler(ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0], input: InferSchemaOutput<TInput>): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
+};
+type AuthStartNoInputGuard<TConfig> = TConfig extends {
+    auth?: {
+        flow?: {
+            start: infer TStart;
+        };
+    };
+} ? TStart extends (...args: infer TArgs) => unknown ? TArgs extends [unknown] ? unknown : {
+    "auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+} : unknown : unknown;
+export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+    id: string;
+    version: string;
+    runtime: "standard" | "shared" | "browser";
+    allowedHosts?: string[];
+    stealth?: {
+        profile: string;
+        platform: StealthPlatform;
+    };
+    proxy?: ProviderProxyConfig;
+    stt?: ProviderSttConfig;
+    browser?: {
+        engine: BrowserEngine;
+    };
+    auth?: AuthConfig;
+    reviewed?: ProviderReviewed;
+    access?: ProviderAccessConfig;
+    secrets?: ProviderSecretDeclaration[];
+    credential?: CredentialDeclaration;
+    context?: ContextDeclaration;
+    meta: {
+        displayName: string;
+        displayNameKey?: string;
+        descriptionKey: string;
+        category: string;
+        tags?: readonly string[];
+        icon?: string;
+        docTitleKey?: string;
+        docDescriptionKey?: string;
+        docSummaryKey?: string;
+        docMarkdownKey?: string;
+        normalizationNotesKeys?: readonly string[];
+        environment?: "staging";
+        purpose?: string;
+        purposeKey?: string;
+        publicProfile?: ProviderPublicProfile;
+        implementationProfile?: ProviderImplementationProfile;
+        contract?: {
+            publicSchemaFieldNames?: "normalized";
+        };
+    };
+    operations: OperationMapConfig<TOperations>;
+    healthMonitor?: ProviderHealthMonitorConfig;
+    healthJourneys?: readonly HealthJourneyDefinition[];
+}
+/** Define one provider operation with schema-driven handler inference. */
+export declare function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(operation: OperationConfig<TInput, TOutput>): OperationDefinition<TInput, TOutput>;
+/** Define a non-JSON provider operation with explicit transport metadata. */
+export declare function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(operation: StreamOperationConfig<TInput, TOutput>): OperationDefinition<TInput, TOutput>;
+export declare function every(interval: string, options?: {
+    jitter?: string;
+}): HealthJourneySchedule;
+export declare function defineSmsOtpMatcher(config: Omit<SmsOtpMatcherDefinition, "extractOtp">): SmsOtpMatcherDefinition;
+export declare function defineHealthJourney(config: HealthJourneyDefinition): HealthJourneyDefinition;
+export declare function defineProvider<TOperations extends Record<string, ProviderOperation>, TConfig extends ProviderConfig<TOperations>>(config: TConfig & AuthStartNoInputGuard<TConfig>): ProviderDefinition & {
+    operations: OperationMapConfig<TOperations>;
+};
+export {};