@apifuse/provider-sdk 2.0.0-beta.1 → 2.1.0-beta.1

package/src/types.ts

@@ -1,5 +1,271 @@
 import type { infer as ZodInfer, ZodType } from "zod";
 
+/** Minimal Standard Schema v1 shape accepted by provider operations. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+	readonly "~standard": {
+		readonly version: 1;
+		readonly vendor: string;
+		readonly validate: (
+			value: unknown,
+		) =>
+			| StandardSchemaV1.Result<Output>
+			| Promise<StandardSchemaV1.Result<Output>>;
+		readonly types?: { readonly input: Input; readonly output: Output };
+	};
+}
+export namespace StandardSchemaV1 {
+	export interface Issue {
+		readonly message: string;
+		readonly path?: readonly (PropertyKey | PathSegment)[];
+	}
+	export interface PathSegment {
+		readonly key: PropertyKey;
+	}
+	export interface SuccessResult<Output> {
+		readonly value: Output;
+	}
+	export interface FailureResult {
+		readonly issues: readonly Issue[];
+	}
+	export type Result<Output> = SuccessResult<Output> | FailureResult;
+}
+/** Schema formats supported by provider operations. */
+export type SchemaLike = ZodType | StandardSchemaV1;
+/** Infer the validated output type produced by a Zod or Standard Schema. */
+export type InferSchemaOutput<TSchema extends SchemaLike> =
+	TSchema extends ZodType
+		? ZodInfer<TSchema>
+		: TSchema extends StandardSchemaV1<unknown, infer Output>
+			? Output
+			: unknown;
+
+export interface OperationInputExample {
+	scenario: string;
+	input: unknown;
+	rationale?: string;
+}
+
+export interface OperationAnnotations {
+	readOnly?: boolean;
+	destructive?: boolean;
+	idempotent?: boolean;
+	/**
+	 * Marks the operation as callable without provider-level authentication.
+	 *
+	 * Provider-level `auth.mode` describes the **majority** auth model of a
+	 * provider; individual operations can still opt out via `openWorld: true`
+	 * when their handler does not consume `ctx.credential`. This is the
+	 * canonical way to declare "this operation is public, even though the
+	 * provider is `credentials`-mode" without splitting the provider into two.
+	 *
+	 * Health-check projections treat `openWorld: true` operations as
+	 * connection-free probes (no `requiresConnection` required, no SA token
+	 * lookup). Future gateway work MAY extend this annotation to bypass
+	 * `X-ApiFuse-Connection-Id` enforcement at proxy time.
+	 *
+	 * Example: Naver Map's `search`, `geocode`, and directions operations
+	 * call public Naver endpoints with no cookies, while `collections` and
+	 * `export` consume the user's session cookie — the provider declares
+	 * `auth.mode: "credentials"` (for the latter) and the former mark
+	 * `openWorld: true`.
+	 */
+	openWorld?: boolean;
+	rateLimit?: {
+		calls: number;
+		window: "minute" | "hour" | "day";
+	};
+	timeoutMs?: number;
+}
+
+export const OPERATION_TIMEOUT_MS_MIN = 1;
+export const OPERATION_TIMEOUT_MS_MAX = 60_000;
+
+export interface OperationRelationships {
+	alternatives?: string[];
+}
+
+/**
+ * Health-check authoring surface owned by `@apifuse/provider-sdk`.
+ *
+ * IMPORTANT (architectural invariant): These types are PURE DATA + assertion
+ * lambdas. They MUST NOT import or reference any health-monitor runtime
+ * surface (scheduler, recorder, gateway client, registry projection types).
+ * Provider declarations remain runtime-agnostic at build time.
+ *
+ * See `openspec/changes/enforce-sdk-operation-health-suite/design.md` §D1.
+ */
+
+/** Polling intervals supported by the health-monitor runtime. */
+export type ProbeInterval =
+	| "30s"
+	| "1m"
+	| "3m"
+	| "5m"
+	| "15m"
+	| "30m"
+	| "1h"
+	| "24h";
+
+export const PROBE_INTERVALS: readonly ProbeInterval[] = [
+	"30s",
+	"1m",
+	"3m",
+	"5m",
+	"15m",
+	"30m",
+	"1h",
+	"24h",
+] as const;
+
+/**
+ * Context passed to a `HealthCheckCase.assertions` lambda.
+ * `data` is typed against the operation's declared output schema (TOutput).
+ */
+export interface HealthCheckAssertionContext<TOutput = unknown> {
+	/** Parsed response body (already validated against operation.output). */
+	readonly data: TOutput;
+	/** HTTP status code returned by the gateway. */
+	readonly status: number;
+	/** Wall-clock duration of the operation invocation, in milliseconds. */
+	readonly durationMs: number;
+}
+
+/**
+ * Optional return value from an assertions lambda. Allows the case to
+ * downgrade to "degraded" without throwing, and to attach a human-friendly
+ * label that surfaces on the status page (e.g., "BTC 95,000,000원").
+ */
+export interface HealthCheckCaseResult {
+	/** Override final status; if omitted, "ok" unless assertion threw. */
+	status?: "ok" | "degraded";
+	/** Optional human-readable label surfaced on the status page. */
+	label?: string;
+}
+
+/**
+ * A single test-case-style verification scenario for an operation.
+ *
+ * Type parameters flow from the OperationDefinition's input/output schemas
+ * so authors get IntelliSense and compile-time errors when accessing fields
+ * that do not exist on the operation's declared output schema.
+ */
+export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
+	/** Human-readable case name; unique within the suite. */
+	name: string;
+	/** Optional longer description shown on ops dashboards. */
+	description?: string;
+	/** Input passed to the operation handler for this case. */
+	input: TInput;
+	/**
+	 * Assertion executed against the operation's response and timing.
+	 *
+	 * - Throw to fail the case (recorded as `down`).
+	 * - Return `{ status: "degraded", label }` to flag without failing.
+	 * - Return `void` (implicit) for `ok`.
+	 *
+	 * MUST NOT access scheduler, recorder, or any runtime type — pure data
+	 * + lambda only.
+	 */
+	assertions: (
+		ctx: HealthCheckAssertionContext<TOutput>,
+	) =>
+		| void
+		| Promise<void>
+		| HealthCheckCaseResult
+		| Promise<HealthCheckCaseResult>;
+	/** Override per-case degradation threshold (ms); falls back to the suite default. */
+	degradedThresholdMs?: number;
+	/** Expected outcome for "negative" cases (e.g., expecting a degraded baseline). Default: `"ok"`. */
+	expectedStatus?: "ok" | "degraded";
+	/** Runtime gate (env-driven); if returns false the case is skipped & logged. */
+	enabled?: () => boolean;
+}
+
+/**
+ * Operation-level health-check suite. At least one case is required when
+ * present. All cases share the suite's interval and default timeout.
+ */
+export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
+	/** Polling interval for the suite. All cases share this cadence. */
+	interval: ProbeInterval;
+	/** Per-case timeout in milliseconds. Default: 30000. */
+	timeoutMs?: number;
+	/** Non-empty list of cases. Empty arrays are rejected at definition time. */
+	cases: [
+		HealthCheckCase<TInput, TOutput>,
+		...HealthCheckCase<TInput, TOutput>[],
+	];
+	/**
+	 * If true, the runtime SHALL invoke `connect()` before `execute()` and
+	 * `disconnect()` after, using the service-account token. The provider
+	 * MUST also declare `healthMonitor.requiredSecrets` for the env values
+	 * the connect ceremony will consume.
+	 */
+	requiresConnection?: boolean;
+}
+
+/**
+ * Explicit, audited opt-out for operations that genuinely cannot be probed
+ * (e.g., destructive mutations, paid-per-call flows). Either `healthCheck`
+ * or `healthCheckUnsupported` SHALL be present on every operation; missing
+ * both is a registry-build error.
+ */
+export interface HealthCheckUnsupported {
+	/** Human-readable explanation. Required, non-empty. */
+	reason: string;
+	/** Optional issue/PR url that revisits the decision. */
+	trackedIn?: string;
+}
+
+/**
+ * Provider-level monitoring metadata for credential-bearing health checks.
+ * Describes ONLY env-secret keys the runtime needs and the service account
+ * to use; SHALL NOT carry probe schedules, sample inputs, or assertion
+ * logic (those remain on `OperationDefinition.healthCheck`).
+ */
+export interface ProviderHealthMonitorConfig {
+	/**
+	 * Env-secret key names (e.g., "HEALTH_MONITOR_CATCHTABLE_PHONE") the
+	 * synthetic-monitor runtime needs to execute probes that declare
+	 * `requiresConnection: true`.
+	 */
+	requiredSecrets?: string[];
+	/**
+	 * Runtime probe overrides keyed by probe id (for example
+	 * "catchtable/auth-flow" or "catchtable/waiting-lifecycle"). Use this for
+	 * health-monitor probes that are provider-scoped or cross-operation and
+	 * therefore cannot declare an `OperationDefinition.healthCheck.interval`.
+	 */
+	probeOverrides?: Record<string, HealthMonitorProbeOverride>;
+	/**
+	 * Override the default service account ID for this provider's probes.
+	 * Defaults to the runtime's `APIFUSE_SERVICE_ACCOUNT_ID` env var.
+	 */
+	serviceAccount?: string;
+}
+
+export interface HealthMonitorProbeOverride {
+	/** Optional runtime interval override. Must be one of PROBE_INTERVALS. */
+	interval?: ProbeInterval;
+}
+
+export interface OperationErrorCode {
+	code: string;
+	status?: number;
+	description: string;
+	retryable?: boolean;
+}
+
+export interface OperationDocMeta {
+	title?: string;
+	description?: string;
+	summary?: string;
+	normalizationNotes?: string[];
+	requestExample?: Record<string, unknown>;
+	responseExample?: unknown;
+	errorCodes?: OperationErrorCode[];
+}
+
 export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
 
 export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
@@ -23,15 +289,11 @@ export interface StealthProfile {
 	headerOrder?: string[];
 }
 
-export type AuthMode = "none" | "credentials" | "oauth2" | "api-key";
+export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2";
 
-export interface AuthField {
-	name: string;
-	label: string;
-	type: "text" | "password" | "otp";
-	required?: boolean;
-	deferred?: boolean;
-}
+export type ConnectionMode = AuthMode;
+
+export type ProviderReviewed = "first-party" | "community" | "staging";
 
 export interface ProviderMeta {
 	displayName: string;
@@ -39,6 +301,12 @@ export interface ProviderMeta {
 	category: string;
 	tags?: string[];
 	icon?: string;
+	docTitle?: string;
+	docDescription?: string;
+	docSummary?: string;
+	normalizationNotes?: string[];
+	environment?: "staging";
+	purpose?: string;
 }
 
 export interface RequestOptions {
@@ -52,9 +320,15 @@ export interface TlsFetchOptions extends RequestOptions {
 	method?: string;
 	body?: string | Buffer;
 	profile?: string;
+	/**
+	 * Defaults to true. Set to false when callers need to inspect upstream
+	 * non-2xx bodies themselves instead of converting them to TransportError.
+	 */
+	throwOnHttpError?: boolean;
 	tls?: {
 		ja3?: string;
 		h2?: Record<string, unknown>;
+		insecureSkipVerify?: boolean;
 	};
 	headerOrder?: string[];
 }
@@ -133,17 +407,6 @@ export interface BrowserClient {
 	newPage(): Promise<unknown>;
 }
 
-export interface SessionStore {
-	get(key: string): Promise<string | null>;
-	set(key: string, value: string, ttl?: string): Promise<void>;
-	delete(key: string): Promise<void>;
-}
-
-export interface StateContext {
-	seal(data: unknown, options?: { ttl?: string }): Promise<string>;
-	unseal<T = unknown>(token: string): Promise<T | null>;
-}
-
 export type TraceAttributeValue = string | number | boolean;
 
 export interface TraceSpan {
@@ -182,53 +445,134 @@ export interface AuthContext {
 	): Promise<string>;
 }
 
+export interface EnvContext {
+	get(key: string): string | undefined;
+}
+
+export interface CredentialContext {
+	mode: AuthMode;
+	get(key: string): string | undefined;
+	getAll(): Record<string, string>;
+	getAccessToken(): string | undefined;
+	getScopes(): string[];
+}
+
+export interface ProviderRequestContext {
+	connectionId?: string;
+	headers: Record<string, string>;
+}
+
+export interface ContextScratchpad {
+	get(key: string): unknown;
+	set(key: string, value: unknown): void;
+	toJSON(): Record<string, unknown>;
+}
+
+export type FlowContextStore = ContextScratchpad;
+
+export interface FlowContext {
+	connectionId?: string;
+	externalRef?: string;
+	tenantId: string;
+	providerId: string;
+	http: HttpClient;
+	env: EnvContext;
+	context: ContextScratchpad;
+}
+
+export interface AuthTurn {
+	kind: string;
+	turnId: string;
+	expiresAt?: string;
+	data?: Record<string, unknown>;
+	expectedInput?: Record<string, unknown>;
+	hint?: string;
+	timing?: {
+		suggestedPollIntervalMs?: number;
+		maxWaitMs?: number;
+	};
+}
+
+export type AuthFlowHandler = (
+	ctx: FlowContext,
+	input?: Record<string, unknown>,
+) => Promise<AuthTurn>;
+
+export interface AuthFlowDefinition {
+	start: AuthFlowHandler;
+	continue: AuthFlowHandler;
+	poll?: AuthFlowHandler;
+	abort?: AuthFlowHandler;
+}
+
 export interface ProviderContext {
+	env: EnvContext;
+	credential: CredentialContext;
+	request?: ProviderRequestContext;
 	http: HttpClient;
 	tls: TlsClient;
 	browser: BrowserClient;
-	session: SessionStore;
-	state: StateContext;
 	trace: TraceContext;
 	auth: AuthContext;
 }
 
 export interface AuthConfig {
 	mode: AuthMode;
-	fields?: AuthField[];
-	exchange?: (
-		ctx: ProviderContext,
-		credentials: Record<string, string>,
-	) => Promise<void>;
-	refresh?: (ctx: ProviderContext) => Promise<void>;
-	refreshPolicy?: {
-		strategy: "reactive" | "proactive" | "both";
-		interval?: string;
-	};
-	disconnect?: (ctx: ProviderContext) => Promise<void>;
+	flow?: AuthFlowDefinition;
+}
+
+export interface ProviderSecretDeclaration {
+	name: string;
+	description?: string;
+	required?: boolean;
+}
+
+export interface CredentialDeclaration {
+	keys: string[];
+	storesReusableSecret?: boolean;
+	justification?: string;
+}
+
+export interface ContextDeclaration {
+	keys: string[];
 }
 
 export interface OperationDefinition<
-	TInput extends ZodType = ZodType,
-	TOutput extends ZodType = ZodType,
+	TInput extends SchemaLike = SchemaLike,
+	TOutput extends SchemaLike = SchemaLike,
 > {
 	description?: string;
+	docs?: OperationDocMeta;
+	whenToUse?: string[];
+	whenNotToUse?: string[];
+	derivations?: Record<string, string>;
+	inputExamples?: OperationInputExample[];
+	annotations?: OperationAnnotations;
+	tags?: string[];
+	relatedOperations?: OperationRelationships;
 	input: TInput;
 	output: TOutput;
-	handler: (
+	handler(
 		ctx: ProviderContext,
-		input: ZodInfer<TInput>,
-	) => Promise<ZodInfer<TOutput>>;
+		input: InferSchemaOutput<TInput>,
+	): Promise<InferSchemaOutput<TOutput>>;
 	fixtures?: {
-		request: ZodInfer<TInput>;
-		response: ZodInfer<TOutput>;
+		request: InferSchemaOutput<TInput>;
+		response: InferSchemaOutput<TOutput>;
 	};
 	hints?: Record<string, string>;
+	healthCheck?: HealthCheckSuite<
+		InferSchemaOutput<TInput>,
+		InferSchemaOutput<TOutput>
+	>;
+	healthCheckUnsupported?: HealthCheckUnsupported;
 }
 
 export interface ProviderDefinition {
 	id: string;
 	version: string;
-	runtime: "standard" | "browser";
+	runtime: "standard" | "shared" | "browser";
+	allowedHosts?: string[];
 	stealth?: {
 		profile: string;
 		platform: StealthPlatform;
@@ -238,6 +582,11 @@ export interface ProviderDefinition {
 		engine: BrowserEngine;
 	};
 	auth?: AuthConfig;
+	reviewed?: ProviderReviewed;
+	secrets?: ProviderSecretDeclaration[];
+	credential?: CredentialDeclaration;
+	context?: ContextDeclaration;
 	meta: ProviderMeta;
-	operations: Record<string, OperationDefinition<ZodType, ZodType>>;
+	operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
+	healthMonitor?: ProviderHealthMonitorConfig;
 }