@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/types.js

@@ -32,6 +32,7 @@ export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
 export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
 export const HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/dist/typescript-module.d.ts

@@ -0,0 +1,39 @@
+/** The TypeScript compiler API surface the source-level lint rules parse with. */
+export type TypeScriptModule = typeof import("typescript");
+/**
+ * What a caller hands over as a compiler module. Typed structurally so the
+ * option does not depend on which `typescript` package the caller's own type
+ * resolution lands on: under a `typescript@7` pin `typeof import("typescript")`
+ * is the native shell's version module, not the compiler API. The members are
+ * optional for the same reason — the shell has none of them — and
+ * `isTypeScriptCompilerModule` decides at runtime whether the module can parse.
+ */
+export type TypeScriptCompilerModuleLike = {
+    readonly createSourceFile?: (...parameters: never[]) => unknown;
+    readonly ScriptTarget?: object;
+    readonly version?: string;
+};
+/**
+ * Package specifiers that may carry the compiler API, in resolution order.
+ *
+ * `typescript@7` (the Go-native toolchain) resolves but its JavaScript entry
+ * exports only `version`/`getExePath` — no `createSourceFile`, so the lint
+ * rules cannot parse with it. The compiler API of that generation is published
+ * as `@typescript/typescript6`, which is what a `typescript@7` dependency tree
+ * (for example the APIFuse monorepo root) installs alongside the shell.
+ */
+export declare const TYPESCRIPT_COMPILER_MODULE_SPECIFIERS: readonly ["typescript", "@typescript/typescript6"];
+/**
+ * True when `candidate` is a loaded module that exposes the parser the lint
+ * rules need. Internal (narrows to the `typescript` module type, which is not
+ * part of the package surface); `lintRuntimeBoundarySources` applies it to the
+ * caller-supplied option.
+ */
+export declare function isTypeScriptCompilerModule(candidate: unknown): candidate is TypeScriptModule;
+/**
+ * Resolve the compiler API through `load`, trying each specifier in order and
+ * accepting the first module that exposes `createSourceFile`. Exposed for the
+ * tests; production code uses `getTypeScript()`.
+ */
+export declare function loadTypeScriptModule(load: (specifier: string) => unknown, specifiers?: readonly string[]): TypeScriptModule;
+export declare function getTypeScript(): TypeScriptModule;

package/dist/typescript-module.js

@@ -0,0 +1,72 @@
+import { createRequire } from "node:module";
+const requireModule = createRequire(import.meta.url);
+/**
+ * Package specifiers that may carry the compiler API, in resolution order.
+ *
+ * `typescript@7` (the Go-native toolchain) resolves but its JavaScript entry
+ * exports only `version`/`getExePath` — no `createSourceFile`, so the lint
+ * rules cannot parse with it. The compiler API of that generation is published
+ * as `@typescript/typescript6`, which is what a `typescript@7` dependency tree
+ * (for example the APIFuse monorepo root) installs alongside the shell.
+ */
+export const TYPESCRIPT_COMPILER_MODULE_SPECIFIERS = [
+    "typescript",
+    "@typescript/typescript6",
+];
+/**
+ * True when `candidate` is a loaded module that exposes the parser the lint
+ * rules need. Internal (narrows to the `typescript` module type, which is not
+ * part of the package surface); `lintRuntimeBoundarySources` applies it to the
+ * caller-supplied option.
+ */
+export function isTypeScriptCompilerModule(candidate) {
+    return (typeof candidate === "object" &&
+        candidate !== null &&
+        typeof candidate.createSourceFile === "function" &&
+        typeof candidate.ScriptTarget === "object");
+}
+function describeCandidate(candidate) {
+    if (typeof candidate === "object" && candidate !== null) {
+        const version = candidate.version;
+        if (typeof version === "string")
+            return `resolved ${version} without a compiler API`;
+    }
+    return "resolved without a compiler API";
+}
+/**
+ * Resolve the compiler API through `load`, trying each specifier in order and
+ * accepting the first module that exposes `createSourceFile`. Exposed for the
+ * tests; production code uses `getTypeScript()`.
+ */
+export function loadTypeScriptModule(load, specifiers = TYPESCRIPT_COMPILER_MODULE_SPECIFIERS) {
+    const attempts = [];
+    for (const specifier of specifiers) {
+        let candidate;
+        try {
+            candidate = load(specifier);
+        }
+        catch {
+            attempts.push(`${specifier}: not resolvable`);
+            continue;
+        }
+        if (isTypeScriptCompilerModule(candidate))
+            return candidate;
+        attempts.push(`${specifier}: ${describeCandidate(candidate)}`);
+    }
+    throw new Error(`The provider source lint needs the TypeScript compiler API (createSourceFile) and none of the resolvable packages provide it — ${attempts.join("; ")}. Install typescript 6.x as a devDependency, or @typescript/typescript6 next to a typescript 7 toolchain, in the dependency tree that installs @apifuse/provider-sdk.`);
+}
+/**
+ * Lazily loaded TypeScript compiler API shared by the source-level lint rules.
+ *
+ * `typeof import(...)` keeps the type without emitting a static import: the
+ * typescript package is a devDependency of the SDK and only the CLI and the
+ * lint rules need it at runtime, which the typescript-import-boundary test
+ * enforces for production sources. Resolution starts at the installed SDK, so
+ * the caller's dependency tree must provide one of
+ * `TYPESCRIPT_COMPILER_MODULE_SPECIFIERS`.
+ */
+let typeScriptModule;
+export function getTypeScript() {
+    typeScriptModule ??= loadTypeScriptModule(requireModule);
+    return typeScriptModule;
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.7",
+	"version": "2.2.0-beta.70",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -15,9 +15,14 @@
 		"src",
 		"!src/__tests__",
 		"!src/__tests__/**",
+		"!src/**/__tests__",
+		"!src/**/__tests__/**",
 		"!src/**/*.test.ts",
+		"!src/**/*.spec.ts",
 		"!src/index.test.ts",
 		"bin",
+		"!bin/__tests__",
+		"!bin/__tests__/**",
 		"README.md",
 		"AUTHORING.md",
 		"CHANGELOG.md",
@@ -61,6 +66,36 @@
 			"import": "./dist/server/index.js",
 			"default": "./dist/server/index.js"
 		},
+		"./runtime/browser": {
+			"types": "./dist/runtime/browser.d.ts",
+			"import": "./dist/runtime/browser.js",
+			"default": "./dist/runtime/browser.js"
+		},
+		"./runtime/native-network": {
+			"types": "./dist/runtime/native-network.d.ts",
+			"import": "./dist/runtime/native-network.js",
+			"default": "./dist/runtime/native-network.js"
+		},
+		"./runtime/prevalidate": {
+			"types": "./dist/runtime/prevalidate.d.ts",
+			"import": "./dist/runtime/prevalidate.js",
+			"default": "./dist/runtime/prevalidate.js"
+		},
+		"./runtime/resolver": {
+			"types": "./dist/runtime/resolver-public.d.ts",
+			"import": "./dist/runtime/resolver-public.js",
+			"default": "./dist/runtime/resolver-public.js"
+		},
+		"./runtime/stealth": {
+			"types": "./dist/runtime/stealth.d.ts",
+			"import": "./dist/runtime/stealth.js",
+			"default": "./dist/runtime/stealth.js"
+		},
+		"./stateful": {
+			"types": "./dist/stateful/index.d.ts",
+			"import": "./dist/stateful/index.js",
+			"default": "./dist/stateful/index.js"
+		},
 		"./testing": {
 			"types": "./dist/testing/index.d.ts",
 			"import": "./dist/testing/index.js",
@@ -75,10 +110,17 @@
 	"scripts": {
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
+		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
+		"lint:test-typesafety": "bun scripts/check-test-typesafety.ts",
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run build",
+		"bench:redaction": "bun scripts/benchmark-request-redaction.ts",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
+		"api:update": "bun run build && bun scripts/api-reports.ts update",
+		"api:check": "bun run build && bun scripts/api-reports.ts check",
+		"verify:chrome-headers": "bun scripts/verify-chrome-header-parity.ts",
+		"changeset:check": "bun scripts/check-changeset.ts",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
@@ -89,18 +131,19 @@
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.5",
 		"@biomejs/biome": "^2.5.0",
+		"@changesets/cli": "^3.0.1",
+		"@microsoft/api-extractor": "^7.58.13",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"typescript": "7.0.2"
+		"ajv": "^8.17",
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
-		"@rgrove/parse-xml": "4.2.2",
+		"@rgrove/parse-xml": "4.2.3",
 		"@types/ms": "^2.1.0",
 		"acorn": "^8.17.0",
-		"ajv": "^8.17",
 		"hono": "^4.12.25",
-		"impit": "0.14.1",
 		"ioredis": "^5.11.1",
 		"ms": "^2.1.3",
 		"playwright": "^1.55.1",
@@ -108,6 +151,9 @@
 		"puppeteer-extra-plugin-stealth": "^2.11.2",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
+		"socks": "^2.8.9",
+		"tough-cookie": "^6.0.2",
+		"wreq-js": "3.0.0",
 		"zod": "^4.4.3"
 	},
 	"repository": {

package/src/auth-turn/index.ts

@@ -24,7 +24,7 @@ export const AUTH_TURN_SCHEMA_ARTIFACT_PATH = "dist/auth-turn/auth-turn.v1.schem
  *
  * This is the exact codification of the runtime validation the SDK applies to
  * ceremony outputs (see `validateCeremonyOutput` in `src/ceremonies`), which
- * compiles this same document. `kind` is an OPEN string on the wire: the known
+ * evaluates this same document. `kind` is an OPEN string on the wire: the known
  * kinds in {@link TURN_KINDS} are tooling metadata, never a wire constraint.
  *
  * The committed artifact at `src/auth-turn/auth-turn.v1.schema.json` (shipped

package/src/auth.ts

@@ -1,4 +1,9 @@
 import { AuthError, ProviderError } from "./errors.js";
+import {
+	declarationInvalidError,
+	DECLARATION_RULE_IDS,
+	type DeclarationViolation,
+} from "./declaration-validation.js";
 import type {
 	AuthAbortData,
 	AuthConfig,
@@ -291,6 +296,25 @@ export interface DefineCredentialsAuthOptions<
 	):
 		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
 		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
+	/**
+	 * Optional re-mint of an expired session from the stored credential, wired
+	 * to `auth.flow.refresh`.
+	 *
+	 * Credential-auth upstreams routinely invalidate a session well before the
+	 * `expiresAt` the provider advertised, which leaves every operation failing
+	 * with a reauth error until a human repeats the whole interactive login.
+	 * Implement this to re-establish the session from what is already stored on
+	 * the connection; the result is resolved exactly like `login`, so it may
+	 * also raise a challenge when the upstream demands one. Omit it when the
+	 * upstream has no non-interactive path and re-authentication genuinely
+	 * requires the user.
+	 */
+	refresh?(
+		ctx: FlowContext,
+		input: Partial<CredentialsAuthInput<TFields>>,
+	):
+		| CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>
+		| Promise<CredentialsAuthLoginResult<TCredentialKeys, keyof TChallenges & string>>;
 }
 
 export interface DefinedCredentialsAuth {
@@ -371,6 +395,27 @@ function normalizeInput<TFields extends CredentialsAuthFields>(
 	return result as CredentialsAuthInput<TFields>;
 }
 
+/**
+ * Refresh variant of {@link normalizeInput}. `login` coerces every declared
+ * field to a string because the interactive turn has already enforced that they
+ * are present; refresh runs with no user present, so an absent field is omitted
+ * rather than turned into an empty string. That keeps "the user did not supply
+ * this" distinguishable from "the user supplied an empty value".
+ */
+function normalizePartialInput<TFields extends CredentialsAuthFields>(
+	fields: TFields,
+	input: Record<string, unknown> | undefined,
+): Partial<CredentialsAuthInput<TFields>> {
+	const result: Record<string, string> = {};
+	for (const name of Object.keys(fields)) {
+		const value = input?.[name];
+		if (typeof value === "string") {
+			result[name] = value;
+		}
+	}
+	return result as Partial<CredentialsAuthInput<TFields>>;
+}
+
 function assertCredentialKeys<TCredentialKeys extends readonly string[]>(
 	credentialKeys: TCredentialKeys,
 	credential: Record<string, unknown>,
@@ -656,6 +701,7 @@ export function defineCredentialsAuth<
 		string,
 		CredentialsAuthChallengeDefinition<CredentialsAuthFields, TCredentialKeys, string>
 	>;
+	validateCredentialsAuthChallenges(challenges);
 
 	return {
 		auth: {
@@ -710,6 +756,44 @@ export function defineCredentialsAuth<
 						completeTurnId,
 					);
 				},
+				// Only advertise refresh when the provider implements it: the
+				// protocol treats the hook's presence as "this connection can be
+				// re-established without the user", and exposing a stub that
+				// cannot actually re-mint would turn a recoverable expiry into a
+				// silent failure.
+				...(options.refresh
+					? {
+							refresh: async (ctx: FlowContext, rawInput?: Record<string, unknown>) => {
+								// A pending challenge belongs to the interactive flow that
+								// raised it; finish it there rather than restarting.
+								const pending = getPendingChallenge(ctx);
+								if (pending) {
+									return await continuePendingChallenge(
+										ctx,
+										options.credentialKeys,
+										challenges,
+										pending,
+										rawInput,
+										completeTurnId,
+									);
+								}
+
+								// Refresh runs without user input, so fields are optional
+								// here — unlike `continue`, missing ones are not a retry.
+								const result = await options.refresh!(
+									ctx,
+									normalizePartialInput(options.fields, rawInput),
+								);
+								return await resolveAuthResult(
+									ctx,
+									options.credentialKeys,
+									challenges,
+									result,
+									completeTurnId,
+								);
+							},
+						}
+					: {}),
 			},
 		},
 		credential: {
@@ -726,3 +810,37 @@ export function defineCredentialsAuth<
 		},
 	};
 }
+
+function validateCredentialsAuthChallenges(
+	challenges: Record<
+		string,
+		CredentialsAuthChallengeDefinition<CredentialsAuthFields, readonly string[], string>
+	>,
+): void {
+	const violations: DeclarationViolation[] = [];
+	for (const [challengeId, challenge] of Object.entries(challenges)) {
+		const fieldCount =
+			challenge.fields && typeof challenge.fields === "object"
+				? Object.keys(challenge.fields).length
+				: 0;
+		const fieldsDeclared =
+			challenge.fields !== undefined && challenge.fields !== null;
+		const hasFields = fieldCount > 0;
+		const hasVerify = typeof challenge.verify === "function";
+		const hasPoll = typeof challenge.poll === "function";
+		const isInteractive = hasFields && hasVerify && !hasPoll;
+		const isPolling = !fieldsDeclared && !hasVerify && hasPoll;
+		const isHybrid = hasFields && hasVerify && hasPoll;
+		const emptyFieldsDeclared = fieldsDeclared && !hasFields;
+		if (!emptyFieldsDeclared && (isInteractive || isPolling || isHybrid)) continue;
+
+		const path = `challenges.${challengeId}`;
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.challengeShape,
+			path,
+			message: "challenge must be interactive, polling, or an explicit hybrid.",
+			fix: `Give ${path} non-empty fields plus verify, poll alone, or all three for a hybrid.`,
+		});
+	}
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}