@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/dist/observability.d.ts

@@ -0,0 +1,5 @@
+export declare const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+export declare const PROVIDER_ERROR_CATEGORIES: readonly ["ok", "timeout", "network", "upstream_http", "upstream_rate_limited", "upstream_auth", "upstream_schema_drift", "proxy_pool", "anti_bot_blocked", "credential_expired", "credential_unavailable", "input_validation", "output_validation", "provider_error", "internal_error", "unclassified"];
+export type ProviderErrorCategory = (typeof PROVIDER_ERROR_CATEGORIES)[number];
+export declare function categoryForStatus(status: number): ProviderErrorCategory;
+export declare function isRetryableCategory(category: ProviderErrorCategory): boolean;

package/dist/observability.js

@@ -0,0 +1,39 @@
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+export const PROVIDER_ERROR_CATEGORIES = [
+    "ok",
+    "timeout",
+    "network",
+    "upstream_http",
+    "upstream_rate_limited",
+    "upstream_auth",
+    "upstream_schema_drift",
+    "proxy_pool",
+    "anti_bot_blocked",
+    "credential_expired",
+    "credential_unavailable",
+    "input_validation",
+    "output_validation",
+    "provider_error",
+    "internal_error",
+    "unclassified",
+];
+export function categoryForStatus(status) {
+    if (status >= 200 && status < 400)
+        return "ok";
+    if (status === 408 || status === 504)
+        return "timeout";
+    if (status === 429)
+        return "upstream_rate_limited";
+    if (status === 401 || status === 403)
+        return "upstream_auth";
+    if (status >= 400)
+        return "upstream_http";
+    return "unclassified";
+}
+export function isRetryableCategory(category) {
+    return (category === "timeout" ||
+        category === "network" ||
+        category === "upstream_rate_limited" ||
+        category === "upstream_http" ||
+        category === "proxy_pool");
+}

package/dist/provider.d.ts

@@ -0,0 +1,9 @@
+export { createFormCeremony } from "./ceremonies";
+export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token";
+export { defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
+export { AuthError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
+export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n";
+export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";
+export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema";
+export type { AuthMode, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types";
+export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types";

package/dist/provider.js

@@ -0,0 +1,8 @@
+export { createFormCeremony } from "./ceremonies";
+export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token";
+export { defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
+export { AuthError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
+export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n";
+export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";
+export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema";
+export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types";

package/dist/public-schema-field-lint.d.ts

@@ -0,0 +1,2 @@
+import type { LintDiagnostic } from "./lint";
+export declare function lintPublicSchemaFieldNames(providerId: string | undefined, operationId: string, input: unknown, output: unknown, enforce: boolean): LintDiagnostic[];

package/dist/public-schema-field-lint.js

@@ -0,0 +1,158 @@
+const ESTABLISHED_APIFUSE_PROTOCOL_FIELDS = new Set(["externalRef"]);
+const UPSTREAM_FIELD_REPLACEMENTS = new Map([
+    ["display", "limit"],
+    ["start", "offset"],
+    ["sort", "sort_by"],
+    ["lprice", "lowest_price"],
+    ["hprice", "highest_price"],
+    ["mallName", "mall_name"],
+    ["productId", "product_id"],
+    ["productType", "product_type_code"],
+    ["lastBuildDate", "upstream_generated_at"],
+    ["meta", "summary"],
+]);
+function isSchema(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        "safeParse" in value &&
+        typeof value.safeParse === "function");
+}
+function getSchemaDef(schema) {
+    const def = schema.def ?? schema._def;
+    return def && typeof def === "object" ? def : {};
+}
+function isSchemaRecord(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return Object.values(value).every(isSchema);
+}
+function getObjectShape(schema) {
+    const rawShape = typeof schema.shape === "function" ? schema.shape() : schema.shape;
+    if (isSchemaRecord(rawShape)) {
+        return rawShape;
+    }
+    const defShape = getSchemaDef(schema).shape;
+    if (typeof defShape === "function") {
+        const resolved = defShape();
+        return isSchemaRecord(resolved) ? resolved : {};
+    }
+    return isSchemaRecord(defShape) ? defShape : {};
+}
+function appendSchemaChildren(children, value) {
+    if (isSchema(value)) {
+        children.push(value);
+        return children;
+    }
+    if (Array.isArray(value)) {
+        children.push(...value.filter(isSchema));
+        return children;
+    }
+    if (value instanceof Set) {
+        children.push(...Array.from(value).filter(isSchema));
+        return children;
+    }
+    if (value instanceof Map) {
+        children.push(...Array.from(value.values()).filter(isSchema));
+        return children;
+    }
+    return children;
+}
+function safeSourceType(schema) {
+    try {
+        return schema.sourceType?.();
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeUnwrap(schema) {
+    try {
+        return schema.unwrap?.();
+    }
+    catch {
+        return undefined;
+    }
+}
+function getTransparentChildSchemas(schema) {
+    const def = getSchemaDef(schema);
+    const children = [];
+    for (const value of [
+        schema.element,
+        schema.items,
+        schema.options,
+        schema.innerType,
+        safeSourceType(schema),
+        safeUnwrap(schema),
+        schema.in,
+        schema.out,
+        schema.left,
+        schema.right,
+        def.schema,
+        def.innerType,
+        def.type,
+        def.valueType,
+        def.item,
+        def.items,
+        def.rest,
+        def.catchall,
+        def.option,
+        def.options,
+        def.pipe,
+        def.payload,
+        def.sourceType,
+        def.left,
+        def.right,
+    ]) {
+        appendSchemaChildren(children, value);
+    }
+    return children;
+}
+function recommendedReplacement(fieldName) {
+    if (/^category\d+$/.test(fieldName)) {
+        return "category_path";
+    }
+    if (UPSTREAM_FIELD_REPLACEMENTS.has(fieldName)) {
+        return UPSTREAM_FIELD_REPLACEMENTS.get(fieldName);
+    }
+    if (/[a-z][A-Z]/.test(fieldName)) {
+        return fieldName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+    }
+    return undefined;
+}
+function collectPublicSchemaFieldDiagnostics(providerId, operationId, schema, basePath, seen = new Set()) {
+    if (!isSchema(schema) || seen.has(schema)) {
+        return [];
+    }
+    seen.add(schema);
+    const diagnostics = [];
+    for (const [fieldName, child] of Object.entries(getObjectShape(schema))) {
+        const fieldPath = `${basePath}.${fieldName}`;
+        const replacement = ESTABLISHED_APIFUSE_PROTOCOL_FIELDS.has(fieldName)
+            ? undefined
+            : recommendedReplacement(fieldName);
+        if (replacement) {
+            diagnostics.push({
+                rule: "public-schema-upstream-field",
+                level: "error",
+                field: fieldPath,
+                message: `Provider "${providerId}" operation "${operationId}" public schema field "${fieldPath}" uses upstream-shaped field "${fieldName}"; use APIFuse field "${replacement}" instead.`,
+            });
+        }
+        diagnostics.push(...collectPublicSchemaFieldDiagnostics(providerId, operationId, child, fieldPath, seen));
+    }
+    for (const child of getTransparentChildSchemas(schema)) {
+        const childPath = schema.element === child ? `${basePath}[]` : basePath;
+        diagnostics.push(...collectPublicSchemaFieldDiagnostics(providerId, operationId, child, childPath, seen));
+    }
+    return diagnostics;
+}
+export function lintPublicSchemaFieldNames(providerId, operationId, input, output, enforce) {
+    if (!providerId || !enforce) {
+        return [];
+    }
+    return [
+        ...collectPublicSchemaFieldDiagnostics(providerId, operationId, input, "input"),
+        ...collectPublicSchemaFieldDiagnostics(providerId, operationId, output, "output"),
+    ];
+}

package/dist/recipes/gov-api.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Check Korean government API result code
+ * Returns true if resultCode matches successCodes (default: ['00', '000', '0000'])
+ */
+export declare function checkResultCode(raw: unknown, successCodes?: string[]): boolean;
+/**
+ * Replace placeholder values with null
+ * e.g., nullIfPlaceholder('해당없음', ['해당없음', '-', '']) → null
+ */
+export declare function nullIfPlaceholder(v: unknown, patterns: string[]): unknown | null;
+/**
+ * Unwrap Korean government API envelope
+ * Handles: {response: {body: {items: {item: ...}}}} nested structure
+ */
+export declare function unwrapGovEnvelope(raw: unknown): unknown;
+/**
+ * Check if Korean government API returned empty result
+ */
+export declare function isEmptyResult(raw: unknown): boolean;

package/dist/recipes/gov-api.js

@@ -0,0 +1,72 @@
+import { unwrapEnvelope } from "../utils/parse";
+function getResultCode(raw) {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    const record = raw;
+    if (typeof record.resultCode === "string") {
+        return record.resultCode;
+    }
+    const response = record.response;
+    const header = response?.header;
+    return typeof header?.resultCode === "string" ? header.resultCode : undefined;
+}
+/**
+ * Check Korean government API result code
+ * Returns true if resultCode matches successCodes (default: ['00', '000', '0000'])
+ */
+export function checkResultCode(raw, successCodes = ["00", "000", "0000"]) {
+    const code = getResultCode(raw);
+    return code ? successCodes.includes(code) : false;
+}
+/**
+ * Replace placeholder values with null
+ * e.g., nullIfPlaceholder('해당없음', ['해당없음', '-', '']) → null
+ */
+export function nullIfPlaceholder(v, patterns) {
+    if (v === null || v === undefined) {
+        return null;
+    }
+    if (typeof v !== "string") {
+        return v;
+    }
+    const normalized = v.trim();
+    return patterns.some((pattern) => normalized === pattern.trim()) ? null : v;
+}
+/**
+ * Unwrap Korean government API envelope
+ * Handles: {response: {body: {items: {item: ...}}}} nested structure
+ */
+export function unwrapGovEnvelope(raw) {
+    const item = unwrapEnvelope(raw, "response.body.items.item");
+    if (Array.isArray(item)) {
+        return item;
+    }
+    if (item !== undefined && item !== null) {
+        return [item];
+    }
+    const items = unwrapEnvelope(raw, "response.body.items");
+    if (Array.isArray(items)) {
+        return items;
+    }
+    if (items !== undefined && items !== null) {
+        return items;
+    }
+    return raw;
+}
+/**
+ * Check if Korean government API returned empty result
+ */
+export function isEmptyResult(raw) {
+    if (getResultCode(raw) === "03") {
+        return true;
+    }
+    const items = unwrapGovEnvelope(raw);
+    if (Array.isArray(items)) {
+        return items.length === 0;
+    }
+    if (items && typeof items === "object") {
+        return Object.keys(items).length === 0;
+    }
+    return false;
+}

package/dist/recipes/rest-api.d.ts

@@ -0,0 +1,21 @@
+export interface PaginationInfo {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Extract pagination info from various REST API response shapes.
+ * Handles: {page, per_page, total}, {meta: {pagination: {...}}}, {currentPage, totalCount, pageSize}
+ */
+export declare function extractPagination(raw: unknown): PaginationInfo | null;
+/**
+ * Normalize error response to a standard format.
+ * Handles: {error: string}, {message: string}, {errors: []}, {error: {message: string}}
+ */
+export declare function normalizeErrorResponse(raw: unknown): {
+    message: string;
+    code?: string;
+} | null;

package/dist/recipes/rest-api.js

@@ -0,0 +1,115 @@
+function toPositiveInteger(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number.parseInt(value, 10);
+        return Number.isNaN(parsed) ? null : parsed;
+    }
+    return null;
+}
+function readPath(raw, path) {
+    if (!raw || typeof raw !== "object") {
+        return undefined;
+    }
+    let current = raw;
+    for (const segment of path.split(".")) {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Extract pagination info from various REST API response shapes.
+ * Handles: {page, per_page, total}, {meta: {pagination: {...}}}, {currentPage, totalCount, pageSize}
+ */
+export function extractPagination(raw) {
+    const candidates = [
+        {
+            page: readPath(raw, "page"),
+            perPage: readPath(raw, "per_page"),
+            total: readPath(raw, "total"),
+        },
+        {
+            page: readPath(raw, "meta.pagination.page"),
+            perPage: readPath(raw, "meta.pagination.per_page"),
+            total: readPath(raw, "meta.pagination.total"),
+        },
+        {
+            page: readPath(raw, "meta.pagination.currentPage"),
+            perPage: readPath(raw, "meta.pagination.pageSize"),
+            total: readPath(raw, "meta.pagination.totalCount"),
+        },
+        {
+            page: readPath(raw, "currentPage"),
+            perPage: readPath(raw, "pageSize"),
+            total: readPath(raw, "totalCount"),
+        },
+    ];
+    for (const candidate of candidates) {
+        const page = toPositiveInteger(candidate.page);
+        const perPage = toPositiveInteger(candidate.perPage);
+        const total = toPositiveInteger(candidate.total);
+        if (page === null || perPage === null || total === null) {
+            continue;
+        }
+        const totalPages = perPage > 0 ? Math.ceil(total / perPage) : 0;
+        return {
+            page,
+            perPage,
+            total,
+            totalPages,
+            hasNext: page < totalPages,
+            hasPrev: page > 1,
+        };
+    }
+    return null;
+}
+function extractMessage(value) {
+    if (typeof value === "string" && value.trim() !== "") {
+        return value;
+    }
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const record = value;
+    if (typeof record.message === "string" && record.message.trim() !== "") {
+        return record.message;
+    }
+    if (typeof record.error === "string" && record.error.trim() !== "") {
+        return record.error;
+    }
+    return null;
+}
+/**
+ * Normalize error response to a standard format.
+ * Handles: {error: string}, {message: string}, {errors: []}, {error: {message: string}}
+ */
+export function normalizeErrorResponse(raw) {
+    if (!raw || typeof raw !== "object") {
+        return null;
+    }
+    const record = raw;
+    const directMessage = extractMessage(record.error) ?? extractMessage(record.message);
+    if (directMessage) {
+        const code = typeof record.code === "string" && record.code.trim() !== ""
+            ? record.code
+            : undefined;
+        return code ? { message: directMessage, code } : { message: directMessage };
+    }
+    const errors = record.errors;
+    if (Array.isArray(errors) && errors.length > 0) {
+        for (const item of errors) {
+            const message = extractMessage(item);
+            if (message) {
+                const code = typeof record.code === "string" && record.code.trim() !== ""
+                    ? record.code
+                    : undefined;
+                return code ? { message, code } : { message };
+            }
+        }
+    }
+    return null;
+}

package/dist/runtime/auth-flow.d.ts

@@ -0,0 +1,14 @@
+import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, StealthClient, SttContext } from "../types";
+export declare function createScratchpad(allowedKeys: string[], initial?: Record<string, unknown>): ContextScratchpad;
+export declare function createFlowContext(options: {
+    http: HttpClient;
+    stealth: StealthClient;
+    env: EnvContext;
+    tenantId: string;
+    providerId: string;
+    connectionId?: string;
+    externalRef?: string;
+    allowedKeys: string[];
+    initialContext?: Record<string, unknown>;
+    stt?: SttContext;
+}): FlowContext;

package/dist/runtime/auth-flow.js

@@ -0,0 +1,44 @@
+import { ContextAccessError } from "../errors";
+import { createUnsupportedSttClient } from "./stt";
+function normalizeAllowedKeys(allowedKeys) {
+    return new Set(allowedKeys.filter((key) => key.trim().length > 0));
+}
+function assertAllowedKey(allowedKeys, key) {
+    if (!allowedKeys.has(key)) {
+        throw new ContextAccessError(`Context key "${key}" is not declared in context.keys.`);
+    }
+}
+export function createScratchpad(allowedKeys, initial = {}) {
+    const normalizedAllowedKeys = normalizeAllowedKeys(allowedKeys);
+    const values = new Map();
+    for (const [key, value] of Object.entries(initial)) {
+        assertAllowedKey(normalizedAllowedKeys, key);
+        values.set(key, value);
+    }
+    return {
+        get(key) {
+            assertAllowedKey(normalizedAllowedKeys, key);
+            return values.get(key);
+        },
+        set(key, value) {
+            assertAllowedKey(normalizedAllowedKeys, key);
+            values.set(key, value);
+        },
+        toJSON() {
+            return Object.fromEntries(values.entries());
+        },
+    };
+}
+export function createFlowContext(options) {
+    return {
+        connectionId: options.connectionId,
+        externalRef: options.externalRef,
+        tenantId: options.tenantId,
+        providerId: options.providerId,
+        http: options.http,
+        stealth: options.stealth,
+        env: options.env,
+        context: createScratchpad(options.allowedKeys, options.initialContext),
+        stt: options.stt ?? createUnsupportedSttClient(),
+    };
+}

package/dist/runtime/browser.d.ts

@@ -0,0 +1,25 @@
+import type { BrowserChallengeRequest, BrowserChallengeResult, BrowserClient as BrowserClientContract, BrowserEngine, BrowserOptions, BrowserPage } from "../types";
+type BrowserPageContract = BrowserPage;
+export type BrowserClientOptions = BrowserOptions & {
+    allowedHosts?: string[];
+    cdpUrl?: string;
+    executablePath?: string;
+    extraArgs?: string[];
+};
+export declare class BrowserClient implements BrowserClientContract {
+    private readonly client;
+    private readonly cdpUrl?;
+    private activePage?;
+    private readonly activePages;
+    private readonly _engine;
+    constructor(options?: BrowserClientOptions);
+    get engine(): BrowserEngine;
+    newPage(): Promise<BrowserPageContract>;
+    rawPage(): Promise<BrowserPageContract>;
+    withIsolatedContext<T>(handler: (page: BrowserPageContract) => Promise<T>): Promise<T>;
+    private activatePage;
+    solveChallenge(request: BrowserChallengeRequest): Promise<BrowserChallengeResult>;
+    close(): Promise<void>;
+}
+export declare function createBrowserClient(options?: BrowserClientOptions): BrowserClient;
+export {};