@sponson/adapters 0.0.0-stage → 0.4.0

package/dist/http.d.ts

@@ -0,0 +1,120 @@
+import { SponsonError, type ErrorCode } from "@sponson/core";
+/** Longest response excerpt an error carries. Error pages can be megabytes; receipts and PR comments must not. */
+export declare const HTTP_ERROR_BODY_LIMIT = 500;
+/** Per-request timeout unless SPONSON_HTTP_TIMEOUT_MS says otherwise. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Retries of a retryable failure unless SPONSON_HTTP_RETRIES says otherwise. */
+export declare const DEFAULT_RETRIES = 4;
+/** First backoff step (doubling, jittered) unless SPONSON_HTTP_RETRY_BASE_MS says otherwise. */
+export declare const DEFAULT_RETRY_BASE_MS = 500;
+/** No single wait is longer than this, whatever Retry-After says. */
+export declare const MAX_RETRY_WAIT_MS = 30000;
+/** The error codes the HTTP client classifies provider failures into; match on them with `isProviderError`. */
+export type ProviderErrorCode = Extract<ErrorCode, `PROVIDER_${string}`>;
+/** Details carried by every provider error. Never the request body. */
+export interface ProviderErrorDetails {
+    adapter: string;
+    method: string;
+    path: string;
+    /** HTTP status, when a response arrived. */
+    status?: number;
+    [k: string]: unknown;
+}
+/**
+ * True when `e` is a provider failure, optionally of the given code(s). Adapters use it to branch on "already
+ * exists" or "not found" instead of reading HTTP statuses. Stable authoring API.
+ */
+export declare function isProviderError(e: unknown, code?: ProviderErrorCode | ProviderErrorCode[]): e is SponsonError & {
+    details: ProviderErrorDetails;
+};
+/** Errors that say "not now" rather than "no": a later poll or run may succeed. */
+export declare function isTransient(e: unknown): boolean;
+/**
+ * Options for `apiClient`. Adapters get one through `clientFor`, which fills `redact` and `env` from the adapter
+ * context.
+ */
+export interface ApiClientOptions {
+    /** Adapter name, for messages and error details. */
+    adapter: string;
+    baseUrl: string;
+    token: string;
+    /** `bearer` sends `Authorization: Bearer <token>`; `header:<name>` sends the token in a custom header. */
+    authHeader?: "bearer" | `header:${string}`;
+    /** Masks known secrets; applied to provider text before it is truncated into an error message. */
+    redact: (text: string) => string;
+    /** Source of SPONSON_HTTP_TIMEOUT_MS / SPONSON_HTTP_RETRIES / SPONSON_HTTP_RETRY_BASE_MS. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Validates a parsed response body and returns it typed. Throw `ShapeError` (or return via the `shape` helpers)
+ * when it is not what the adapter consumes; the client turns that into PROVIDER_RESPONSE naming the endpoint.
+ * Stable authoring API.
+ */
+export type Shape<T> = (body: unknown) => T;
+/**
+ * Thrown by a `Shape` when a response body is not what the adapter expects; the client reports it as
+ * PROVIDER_RESPONSE. Stable authoring API.
+ */
+export declare class ShapeError extends Error {
+    constructor(message: string);
+}
+/**
+ * A JSON client bound to one provider: retries, timeouts and error classification are built in. Get one from
+ * `clientFor`. Stable authoring API.
+ */
+export interface ApiClient {
+    readonly adapter: string;
+    get<T = unknown>(path: string, shape?: Shape<T>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, shape?: Shape<T>, opts?: WriteOptions): Promise<T>;
+    /** PUT replaces the target, so it is retried after a 502/503/504 or a dropped connection like GET. */
+    put<T = unknown>(path: string, body?: unknown, shape?: Shape<T>): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, shape?: Shape<T>, opts?: WriteOptions): Promise<T>;
+    delete<T = unknown>(path: string, shape?: Shape<T>): Promise<T>;
+}
+/** Options for a POST or PATCH. Stable authoring API. */
+export interface WriteOptions {
+    /**
+     * The request may safely be sent twice: it sets state rather than adding to it (a PATCH that replaces a whole
+     * list, a POST with an idempotency key). Then a 502/503/504 or a dropped connection is retried as for GET;
+     * otherwise only refusals (429, 423) are, since the first attempt may have taken effect.
+     */
+    idempotent?: boolean;
+}
+/** Redact first, then flatten and truncate: truncating first could cut a secret so the redactor no longer sees it. */
+export declare function excerptOf(body: string, redact: (s: string) => string): string;
+/** Retry-After as milliseconds: delta-seconds or an HTTP date. Undefined when absent or unparseable. */
+export declare function retryAfterMs(header: string | null, now?: number): number | undefined;
+/** Exponential backoff with jitter: attempt 1 waits base·[0.5, 1), attempt 2 base·[1, 2), … */
+export declare function backoffMs(attempt: number, baseMs: number, random?: () => number): number;
+/**
+ * The PROVIDER_* code for a non-2xx response (status and body). Exported for adapters that talk to a provider
+ * without `apiClient`.
+ */
+export declare function classifyStatus(status: number, body: string): ProviderErrorCode;
+/**
+ * Build an `ApiClient`. Adapters should call `clientFor(actx, ...)` instead, which wires redaction and the
+ * environment.
+ */
+export declare function apiClient(opts: ApiClientOptions): ApiClient;
+/** True for a plain JSON object (not null, not an array). For hand-written `Shape`s. Stable authoring API. */
+export declare function isObject(v: unknown): v is Record<string, unknown>;
+/** `v` must be an object; returns it. Stable authoring API. */
+export declare function obj(v: unknown, what: string): Record<string, unknown>;
+/** `v` must be an array of objects each having the string fields named; returns them typed. Stable authoring API. */
+export declare function records<K extends string>(v: unknown, what: string, fields: readonly K[]): Array<Record<K, string> & Record<string, unknown>>;
+/** One page of a list, as the `page` callback of `listAll` describes it. Stable authoring API. */
+export interface Page<T> {
+    items: T[];
+    /** Query parameters for the next page, or null when this was the last one. */
+    next: Record<string, string> | null;
+}
+/** Hard stop against a provider that keeps returning a cursor. */
+export declare const MAX_PAGES = 1000;
+/**
+ * Fetch every page of a list. `page` validates one response body and says how to ask for the next page.
+ * Stops on a null cursor, an empty page, or a cursor seen before (a provider that repeats the last cursor).
+ * Stable authoring API.
+ */
+export declare function listAll<T>(api: ApiClient, path: string, page: (body: unknown, pageNo: number) => Page<T>): Promise<T[]>;
+/** `path` with `extra` appended as query parameters (after any it already has). Stable authoring API. */
+export declare function withQuery(path: string, extra: Record<string, string>): string;

package/dist/http.js

@@ -0,0 +1,291 @@
+/**
+ * The one HTTP layer every adapter uses: timeout, retry policy, failure classification, response-shape checks and
+ * pagination. Adapters never see a raw fetch error or a non-2xx status; they see a SponsonError with a PROVIDER_*
+ * code, so "already exists" (→ re-read and claim), "gone" (→ fine on delete) and "try later" are decided here once.
+ *
+ * Part of the stable adapter authoring API (see packages/adapters/src/index.ts): ApiClient, Page, Shape,
+ * ShapeError, isObject, obj, records, listAll, withQuery, isProviderError. The rest may change.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+import { SponsonError, isSponsonError } from "@sponson/core";
+/** Longest response excerpt an error carries. Error pages can be megabytes; receipts and PR comments must not. */
+export const HTTP_ERROR_BODY_LIMIT = 500;
+/** Per-request timeout unless SPONSON_HTTP_TIMEOUT_MS says otherwise. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+/** Retries of a retryable failure unless SPONSON_HTTP_RETRIES says otherwise. */
+export const DEFAULT_RETRIES = 4;
+/** First backoff step (doubling, jittered) unless SPONSON_HTTP_RETRY_BASE_MS says otherwise. */
+export const DEFAULT_RETRY_BASE_MS = 500;
+/** No single wait is longer than this, whatever Retry-After says. */
+export const MAX_RETRY_WAIT_MS = 30_000;
+/**
+ * True when `e` is a provider failure, optionally of the given code(s). Adapters use it to branch on "already
+ * exists" or "not found" instead of reading HTTP statuses. Stable authoring API.
+ */
+export function isProviderError(e, code) {
+    if (!isSponsonError(e) || !e.code.startsWith("PROVIDER_"))
+        return false;
+    if (code === undefined)
+        return true;
+    return Array.isArray(code) ? code.includes(e.code) : e.code === code;
+}
+/** Errors that say "not now" rather than "no": a later poll or run may succeed. */
+export function isTransient(e) {
+    return isProviderError(e, ["PROVIDER_TRANSIENT", "PROVIDER_TIMEOUT"]);
+}
+/**
+ * Thrown by a `Shape` when a response body is not what the adapter expects; the client reports it as
+ * PROVIDER_RESPONSE. Stable authoring API.
+ */
+export class ShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ShapeError";
+    }
+}
+/** Methods whose repetition is harmless, so 5xx and network errors are retried. */
+const IDEMPOTENT = new Set(["GET", "HEAD", "DELETE", "PUT"]);
+/** Retried for any method: the provider refused before doing anything (rate limit, Neon's "operation running"). */
+const REFUSED_STATUSES = new Set([429, 423]);
+/** Retried only for idempotent methods: the request may or may not have been executed. */
+const UNAVAILABLE_STATUSES = new Set([502, 503, 504]);
+function policyFrom(env = {}) {
+    const num = (name, fallback, min) => {
+        const raw = env[name];
+        if (raw === undefined || raw === "")
+            return fallback;
+        const n = Number(raw);
+        return Number.isFinite(n) && n >= min ? n : fallback;
+    };
+    return {
+        timeoutMs: num("SPONSON_HTTP_TIMEOUT_MS", DEFAULT_TIMEOUT_MS, 1),
+        retries: Math.floor(num("SPONSON_HTTP_RETRIES", DEFAULT_RETRIES, 0)),
+        baseMs: num("SPONSON_HTTP_RETRY_BASE_MS", DEFAULT_RETRY_BASE_MS, 0),
+    };
+}
+/** Redact first, then flatten and truncate: truncating first could cut a secret so the redactor no longer sees it. */
+export function excerptOf(body, redact) {
+    const flat = redact(body).replace(/\s+/g, " ").trim();
+    return flat.length > HTTP_ERROR_BODY_LIMIT ? `${flat.slice(0, HTTP_ERROR_BODY_LIMIT)}… (${flat.length} chars)` : flat;
+}
+/** Retry-After as milliseconds: delta-seconds or an HTTP date. Undefined when absent or unparseable. */
+export function retryAfterMs(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const t = header.trim();
+    if (/^\d+(\.\d+)?$/.test(t))
+        return Number(t) * 1000;
+    const at = Date.parse(t);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+/** Exponential backoff with jitter: attempt 1 waits base·[0.5, 1), attempt 2 base·[1, 2), … */
+export function backoffMs(attempt, baseMs, random = Math.random) {
+    const ceiling = baseMs * 2 ** (attempt - 1);
+    return Math.min(MAX_RETRY_WAIT_MS, ceiling / 2 + random() * (ceiling / 2));
+}
+/** "Already exists"-type answers. 409 always; 400/422 when the body says so (Clerk, Vercel use those statuses). */
+const CONFLICT_BODY = /already[ _-]?exists|duplicate|ENV_CONFLICT|_exists\b/i;
+/**
+ * The PROVIDER_* code for a non-2xx response (status and body). Exported for adapters that talk to a provider
+ * without `apiClient`.
+ */
+export function classifyStatus(status, body) {
+    if (status === 401 || status === 403)
+        return "PROVIDER_AUTH";
+    if (status === 404)
+        return "PROVIDER_NOT_FOUND";
+    if (status === 409)
+        return "PROVIDER_CONFLICT";
+    if ((status === 400 || status === 422) && CONFLICT_BODY.test(body))
+        return "PROVIDER_CONFLICT";
+    if (REFUSED_STATUSES.has(status) || status >= 500)
+        return "PROVIDER_TRANSIENT";
+    return "PROVIDER_INVALID";
+}
+const DESCRIBE = {
+    PROVIDER_TRANSIENT: "temporarily unavailable",
+    PROVIDER_CONFLICT: "conflict",
+    PROVIDER_NOT_FOUND: "not found",
+    PROVIDER_AUTH: "not authorised",
+    PROVIDER_INVALID: "rejected the request",
+    PROVIDER_TIMEOUT: "timed out",
+    PROVIDER_RESPONSE: "unexpected response",
+};
+class Attempt {
+    code;
+    retryable;
+    message;
+    status;
+    waitMs;
+    constructor(code, retryable, message, status, waitMs) {
+        this.code = code;
+        this.retryable = retryable;
+        this.message = message;
+        this.status = status;
+        this.waitMs = waitMs;
+    }
+}
+/**
+ * A 2xx response body as `shape` wants it (parsed JSON when there is no shape; undefined for an empty body with no
+ * shape), or what is wrong with it.
+ */
+function decode(text, shape, redact) {
+    if (!text)
+        return shape ? { problem: "empty response body" } : { value: undefined };
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { problem: `response is not JSON: ${excerptOf(text, redact)}` };
+    }
+    if (!shape)
+        return { value: parsed };
+    try {
+        return { value: shape(parsed) };
+    }
+    catch (e) {
+        if (e instanceof ShapeError)
+            return { problem: e.message };
+        throw e;
+    }
+}
+/**
+ * Build an `ApiClient`. Adapters should call `clientFor(actx, ...)` instead, which wires redaction and the
+ * environment.
+ */
+export function apiClient(opts) {
+    let base = opts.baseUrl;
+    while (base.endsWith("/"))
+        base = base.slice(0, -1);
+    const auth = opts.authHeader ?? "bearer";
+    const policy = policyFrom(opts.env);
+    const headers = { accept: "application/json" };
+    if (auth === "bearer")
+        headers.authorization = `Bearer ${opts.token}`;
+    else
+        headers[auth.slice("header:".length)] = opts.token;
+    const fail = (code, method, path, detail, status, extra = {}) => new SponsonError(code, `${opts.adapter}: ${method} ${path} → ${status ?? DESCRIBE[code]}${detail ? `: ${detail}` : ""}`, {
+        adapter: opts.adapter,
+        method,
+        path,
+        ...(status !== undefined ? { status } : {}),
+        ...extra,
+    });
+    async function once(method, path, body, idempotent) {
+        const controller = new AbortController();
+        const init = body === undefined
+            ? { method, headers: { ...headers }, signal: controller.signal }
+            : { method, headers: { ...headers, "content-type": "application/json" }, body: JSON.stringify(body), signal: controller.signal };
+        const timer = setTimeout(() => controller.abort(), policy.timeoutMs);
+        try {
+            const res = await fetch(base + path, init);
+            const text = await res.text(); // the timer also bounds a body that never finishes
+            if (res.ok)
+                return { status: res.status, text };
+            const code = classifyStatus(res.status, text);
+            const retryable = REFUSED_STATUSES.has(res.status) || (idempotent && UNAVAILABLE_STATUSES.has(res.status));
+            return new Attempt(code, retryable, excerptOf(text, opts.redact), res.status, retryAfterMs(res.headers.get("retry-after")));
+        }
+        catch (e) {
+            if (controller.signal.aborted)
+                return new Attempt("PROVIDER_TIMEOUT", false, `no response within ${policy.timeoutMs}ms (SPONSON_HTTP_TIMEOUT_MS)`);
+            // `fetch failed` alone says nothing; the cause (ECONNREFUSED, ECONNRESET, ENOTFOUND) does.
+            const cause = e.cause?.message ?? e.message;
+            // A write whose connection dropped may have happened; only idempotent requests are repeated.
+            return new Attempt("PROVIDER_TRANSIENT", idempotent, `${base}${path}: ${opts.redact(cause)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async function call(method, path, body, shape, write) {
+        const idempotent = write?.idempotent ?? IDEMPOTENT.has(method);
+        for (let attempt = 1;; attempt++) {
+            const r = await once(method, path, body, idempotent);
+            if (r instanceof Attempt) {
+                if (r.retryable && attempt <= policy.retries) {
+                    await sleep(Math.min(MAX_RETRY_WAIT_MS, r.waitMs ?? backoffMs(attempt, policy.baseMs)));
+                    continue;
+                }
+                const note = r.retryable ? ` (after ${attempt} attempts)` : "";
+                throw fail(r.code, method, path, r.message + note, r.status, r.retryable ? { attempts: attempt } : {});
+            }
+            const d = decode(r.text, shape, opts.redact);
+            if ("problem" in d)
+                throw fail("PROVIDER_RESPONSE", method, path, d.problem, r.status);
+            return d.value;
+        }
+    }
+    return {
+        adapter: opts.adapter,
+        get: (path, shape) => call("GET", path, undefined, shape),
+        post: (path, body, shape, write) => call("POST", path, body, shape, write),
+        put: (path, body, shape) => call("PUT", path, body, shape),
+        patch: (path, body, shape, write) => call("PATCH", path, body, shape, write),
+        delete: (path, shape) => call("DELETE", path, undefined, shape),
+    };
+}
+// ---------------------------------------------------------------------------
+// Shape helpers: small checks with messages that name the field, instead of a TypeError three frames later.
+// ---------------------------------------------------------------------------
+/** True for a plain JSON object (not null, not an array). For hand-written `Shape`s. Stable authoring API. */
+export function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** `v` must be an object; returns it. Stable authoring API. */
+export function obj(v, what) {
+    if (!isObject(v))
+        throw new ShapeError(`expected ${what} to be an object, got ${kindOf(v)}`);
+    return v;
+}
+/** `v` must be an array of objects each having the string fields named; returns them typed. Stable authoring API. */
+export function records(v, what, fields) {
+    if (!Array.isArray(v))
+        throw new ShapeError(`expected ${what} to be an array, got ${kindOf(v)}`);
+    return v.map((item, i) => {
+        const o = obj(item, `${what}[${i}]`);
+        for (const f of fields)
+            if (typeof o[f] !== "string")
+                throw new ShapeError(`expected ${what}[${i}].${f} to be a string, got ${kindOf(o[f])}`);
+        return o;
+    });
+}
+function kindOf(v) {
+    return v === null ? "null" : Array.isArray(v) ? "an array" : typeof v;
+}
+/** Hard stop against a provider that keeps returning a cursor. */
+export const MAX_PAGES = 1000;
+/**
+ * Fetch every page of a list. `page` validates one response body and says how to ask for the next page.
+ * Stops on a null cursor, an empty page, or a cursor seen before (a provider that repeats the last cursor).
+ * Stable authoring API.
+ */
+export async function listAll(api, path, page) {
+    const out = [];
+    const seen = new Set();
+    let query = {};
+    for (let n = 0;; n++) {
+        if (n >= MAX_PAGES)
+            throw new SponsonError("PROVIDER_RESPONSE", `${api.adapter}: GET ${path} returned more than ${MAX_PAGES} pages`, { adapter: api.adapter, method: "GET", path });
+        const p = await api.get(withQuery(path, query), (b) => page(b, n));
+        out.push(...p.items);
+        if (!p.next || p.items.length === 0)
+            break;
+        const key = JSON.stringify(p.next);
+        if (seen.has(key))
+            break;
+        seen.add(key);
+        query = p.next;
+    }
+    return out;
+}
+/** `path` with `extra` appended as query parameters (after any it already has). Stable authoring API. */
+export function withQuery(path, extra) {
+    const entries = Object.entries(extra);
+    if (entries.length === 0)
+        return path;
+    const q = new URLSearchParams(entries).toString();
+    return path.includes("?") ? `${path}&${q}` : `${path}?${q}`;
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAkB,MAAM,eAAe,CAAC;AAE7E,kHAAkH;AAClH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,yEAAyE;AACzE,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,gGAAgG;AAChG,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,qEAAqE;AACrE,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAexC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAU,EAAE,IAA8C;IACxF,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACxE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAyB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;AAC5F,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC,CAAC;AACxE,CAAC;AA0BD;;;GAGG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AA0BD,mFAAmF;AACnF,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAC7D,mHAAmH;AACnH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,0FAA0F;AAC1F,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAQtD,SAAS,UAAU,CAAC,MAAyB,EAAE;IAC7C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAE,GAAW,EAAU,EAAE;QAClE,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,QAAQ,CAAC;QACrD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvD,CAAC,CAAC;IACF,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,yBAAyB,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAChE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,sBAAsB,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;QACpE,MAAM,EAAE,GAAG,CAAC,4BAA4B,EAAE,qBAAqB,EAAE,CAAC,CAAC;KACpE,CAAC;AACJ,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,MAA6B;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,OAAO,IAAI,CAAC,MAAM,GAAG,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,MAAM,IAAI,CAAC,MAAM,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACxH,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,YAAY,CAAC,MAAqB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAClE,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACrD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,MAAc,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM;IAC7E,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,mHAAmH;AACnH,MAAM,aAAa,GAAG,uDAAuD,CAAC;AAE9E;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,IAAY;IACzD,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,eAAe,CAAC;IAC7D,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,oBAAoB,CAAC;IAChD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,mBAAmB,CAAC;IAC/C,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,mBAAmB,CAAC;IAC/F,IAAI,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,GAAG;QAAE,OAAO,oBAAoB,CAAC;IAC/E,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,MAAM,QAAQ,GAAsC;IAClD,kBAAkB,EAAE,yBAAyB;IAC7C,iBAAiB,EAAE,UAAU;IAC7B,kBAAkB,EAAE,WAAW;IAC/B,aAAa,EAAE,gBAAgB;IAC/B,gBAAgB,EAAE,sBAAsB;IACxC,gBAAgB,EAAE,WAAW;IAC7B,iBAAiB,EAAE,qBAAqB;CACzC,CAAC;AAEF,MAAM,OAAO;IAEA;IACA;IACA;IACA;IACA;IALX,YACW,IAAuB,EACvB,SAAkB,EAClB,OAAe,EACf,MAAe,EACf,MAAe;QAJf,SAAI,GAAJ,IAAI,CAAmB;QACvB,cAAS,GAAT,SAAS,CAAS;QAClB,YAAO,GAAP,OAAO,CAAQ;QACf,WAAM,GAAN,MAAM,CAAS;QACf,WAAM,GAAN,MAAM,CAAS;IACvB,CAAC;CACL;AAED;;;GAGG;AACH,SAAS,MAAM,CAAI,IAAY,EAAE,KAA2B,EAAE,MAA6B;IACzF,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAc,EAAE,CAAC;IACzF,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,yBAAyB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,MAAW,EAAE,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;IAClC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,UAAU;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3D,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAsB;IAC9C,IAAI,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;IACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,IAAI,QAAQ,CAAC;IACzC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,OAAO,GAA2B,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACvE,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC;;QACjE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IAExD,MAAM,IAAI,GAAG,CAAC,IAAuB,EAAE,MAAc,EAAE,IAAY,EAAE,MAAc,EAAE,MAAe,EAAE,QAAiC,EAAE,EAAgB,EAAE,CACzJ,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,KAAK,MAAM,IAAI,IAAI,MAAM,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE;QACvH,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM;QACN,IAAI;QACJ,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,KAAK;KACT,CAAC,CAAC;IAEL,KAAK,UAAU,IAAI,CAAC,MAAc,EAAE,IAAY,EAAE,IAAa,EAAE,UAAmB;QAClF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,IAAI,GACR,IAAI,KAAK,SAAS;YAChB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE;YAChE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;QACrI,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACrE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC;YAC3C,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,mDAAmD;YAClF,IAAI,GAAG,CAAC,EAAE;gBAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC9C,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;YAC3G,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QAC9H,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,IAAI,OAAO,CAAC,kBAAkB,EAAE,KAAK,EAAE,sBAAsB,MAAM,CAAC,SAAS,8BAA8B,CAAC,CAAC;YACnJ,2FAA2F;YAC3F,MAAM,KAAK,GAAI,CAA+B,CAAC,KAAK,EAAE,OAAO,IAAK,CAAW,CAAC,OAAO,CAAC;YACtF,6FAA6F;YAC7F,OAAO,IAAI,OAAO,CAAC,oBAAoB,EAAE,UAAU,EAAE,GAAG,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChG,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED,KAAK,UAAU,IAAI,CAAI,MAAc,EAAE,IAAY,EAAE,IAAa,EAAE,KAAgB,EAAE,KAAoB;QACxG,MAAM,UAAU,GAAG,KAAK,EAAE,UAAU,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/D,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;YACrD,IAAI,CAAC,YAAY,OAAO,EAAE,CAAC;gBACzB,IAAI,CAAC,CAAC,SAAS,IAAI,OAAO,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC7C,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,CAAC,MAAM,IAAI,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACxF,SAAS;gBACX,CAAC;gBACD,MAAM,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,OAAO,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,MAAM,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACzG,CAAC;YACD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,SAAS,IAAI,CAAC;gBAAE,MAAM,IAAI,CAAC,mBAAmB,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;YACvF,OAAO,CAAC,CAAC,KAAK,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC;QACzD,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC;QAC1E,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC;QAC1D,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC;QAC5E,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC;KAChE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,4GAA4G;AAC5G,8EAA8E;AAE9E,8GAA8G;AAC9G,MAAM,UAAU,QAAQ,CAAC,CAAU;IACjC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,GAAG,CAAC,CAAU,EAAE,IAAY;IAC1C,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,YAAY,IAAI,yBAAyB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7F,OAAO,CAAC,CAAC;AACX,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,OAAO,CAAmB,CAAU,EAAE,IAAY,EAAE,MAAoB;IACtF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,YAAY,IAAI,wBAAwB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACvB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;QACrC,KAAK,MAAM,CAAC,IAAI,MAAM;YAAE,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAAE,MAAM,IAAI,UAAU,CAAC,YAAY,IAAI,IAAI,CAAC,KAAK,CAAC,wBAAwB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC9I,OAAO,CAAgD,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,MAAM,CAAC,CAAU;IACxB,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AACxE,CAAC;AAaD,kEAAkE;AAClE,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAI,GAAc,EAAE,IAAY,EAAE,IAAgD;IAC7G,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,IAAI,KAAK,GAA2B,EAAE,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,SAAS;YAAE,MAAM,IAAI,YAAY,CAAC,mBAAmB,EAAE,GAAG,GAAG,CAAC,OAAO,SAAS,IAAI,uBAAuB,SAAS,QAAQ,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpL,MAAM,CAAC,GAAY,MAAM,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5E,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACrB,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,MAAM;QACzB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC;IACjB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAA6B;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAClD,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;AAC9D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { Registry } from "@sponson/core";
+/**
+ * The stable adapter authoring API: what templates/adapter (`pnpm new:adapter`) uses, and what an out-of-tree
+ * adapter may rely on across minor releases. From common.ts: the helpers below (see the comment at its top).
+ * From http.ts: `ApiClient`, `Page`, `Shape`, `ShapeError`, `isObject`, `obj`, `records`, `listAll`,
+ * `withQuery` and `isProviderError`; the rest of http.ts is exported for the built-in adapters and tests.
+ * scenarios/tooling/new-adapter.test.ts fails if the template imports a helper that is not exported here.
+ */
+export { clientFor, requireEnv, optionalEnv, requireProvider, diffValue, desiredSide, assertNoPending, deleteIgnoringNotFound, paramError, stringParam } from "./common.js";
+export * from "./http.js";
+export * from "./neon.js";
+export * from "./vercel.js";
+export * from "./clerk.js";
+export * from "./secrets.js";
+/** Every built-in adapter and secret source. The CLI uses this; tests build narrower registries. */
+export declare function createRegistry(): Registry;

package/dist/index.js

@@ -0,0 +1,23 @@
+import { Registry } from "@sponson/core";
+import { clerkAdapter } from "./clerk.js";
+import { neonAdapter } from "./neon.js";
+import { awsSecretsManagerSource, dopplerSecretSource, envSecretSource, gcpSecretManagerSource, opSecretSource } from "./secrets.js";
+import { vercelAdapter } from "./vercel.js";
+/**
+ * The stable adapter authoring API: what templates/adapter (`pnpm new:adapter`) uses, and what an out-of-tree
+ * adapter may rely on across minor releases. From common.ts: the helpers below (see the comment at its top).
+ * From http.ts: `ApiClient`, `Page`, `Shape`, `ShapeError`, `isObject`, `obj`, `records`, `listAll`,
+ * `withQuery` and `isProviderError`; the rest of http.ts is exported for the built-in adapters and tests.
+ * scenarios/tooling/new-adapter.test.ts fails if the template imports a helper that is not exported here.
+ */
+export { clientFor, requireEnv, optionalEnv, requireProvider, diffValue, desiredSide, assertNoPending, deleteIgnoringNotFound, paramError, stringParam } from "./common.js";
+export * from "./http.js";
+export * from "./neon.js";
+export * from "./vercel.js";
+export * from "./clerk.js";
+export * from "./secrets.js";
+/** Every built-in adapter and secret source. The CLI uses this; tests build narrower registries. */
+export function createRegistry() {
+    return new Registry().addAdapter(neonAdapter).addAdapter(vercelAdapter).addAdapter(clerkAdapter).addSecretSource(envSecretSource).addSecretSource(dopplerSecretSource()).addSecretSource(opSecretSource()).addSecretSource(awsSecretsManagerSource()).addSecretSource(gcpSecretManagerSource());
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,eAAe,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACrI,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,sBAAsB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5K,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAE7B,oGAAoG;AACpG,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,QAAQ,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC,eAAe,CAAC,mBAAmB,EAAE,CAAC,CAAC,eAAe,CAAC,cAAc,EAAE,CAAC,CAAC,eAAe,CAAC,uBAAuB,EAAE,CAAC,CAAC,eAAe,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAClS,CAAC"}

package/dist/neon.d.ts

@@ -0,0 +1,8 @@
+import { type ResourceAdapter } from "@sponson/core";
+/** Neon's API base URL; `NEON_API_URL` overrides it (the sim and tests use that). */
+export declare const NEON_DEFAULT_API_URL = "https://console.neon.tech/api/v2";
+/**
+ * Neon: op `branch` creates a database branch per scope and outputs its connection string (sensitive). Needs
+ * `NEON_API_KEY` and `providers.neon.project`.
+ */
+export declare const neonAdapter: ResourceAdapter;

package/dist/neon.js

@@ -0,0 +1,167 @@
+import { canonicalJson, isPendingMarker, sha256 } from "@sponson/core";
+import { ABSENT, assertNoPending, clientFor, deleteIgnoringNotFound, desiredSide, optionalEnv, paramError, requireEnv, requireProvider, stringParam } from "./common.js";
+import { ShapeError, isProviderError, listAll, obj, records } from "./http.js";
+/** The environment neon reads; declared once, used by the code below and by the generated docs. */
+const ABOUT = { credentialEnv: "NEON_API_KEY", baseUrlEnv: "NEON_API_URL" };
+/** Neon's API base URL; `NEON_API_URL` overrides it (the sim and tests use that). */
+export const NEON_DEFAULT_API_URL = "https://console.neon.tech/api/v2";
+function client(actx) {
+    const token = requireEnv(actx.env, ABOUT.credentialEnv, "neon");
+    const project = requireProvider(actx, "project", "neon");
+    return { api: clientFor(actx, "neon", { baseUrl: optionalEnv(actx.env, ABOUT.baseUrlEnv) ?? NEON_DEFAULT_API_URL, token }), project };
+}
+function branchKey(name) {
+    return `${BRANCH_PREFIX}${name}`;
+}
+const BRANCH_PREFIX = "branch:";
+/** Identity hash: name and parent, the two things that define a branch for us. A replacement shows as a new provider id. */
+function branchHash(b) {
+    return sha256(canonicalJson({ name: b.name, parent_id: b.parent_id }));
+}
+function record(b) {
+    return { key: branchKey(b.name), id: b.id, hash: branchHash(b), label: `Neon branch ${b.name}` };
+}
+function parseBranches(v, what) {
+    return records(v, what, ["id", "name"]).map((b, i) => {
+        if (b.parent_id !== undefined && b.parent_id !== null && typeof b.parent_id !== "string")
+            throw new ShapeError(`expected ${what}[${i}].parent_id to be a string or null`);
+        return { id: b.id, name: b.name, parent_id: b.parent_id ?? null, default: b.default === true, primary: b.primary === true };
+    });
+}
+/** `{ branches, pagination: { next } }`; the next page is `?cursor=<next>`. Older responses call it `cursor`. */
+function branchPage(body) {
+    const o = obj(body, "the branch list");
+    const items = parseBranches(o.branches, "`branches`");
+    const p = o.pagination;
+    const cursor = p && typeof p === "object" ? (p.next ?? p.cursor) : undefined;
+    return { items, next: typeof cursor === "string" && cursor !== "" ? { cursor } : null };
+}
+async function listBranches(c) {
+    return listAll(c.api, `/projects/${c.project}/branches`, branchPage);
+}
+/** The database a branch's connection string points at: `neondb` (a new project's default) if present, else the first one. */
+const DEFAULT_DATABASE = "neondb";
+/**
+ * The branch's endpoint host and connection string. GET /projects/:id/connection_uri requires `database_name` and
+ * `role_name`; both come from the branch's own database list (the database's `owner_name` is the role), so a
+ * project whose database or role is not named like a new project's defaults still works.
+ */
+async function outputsFor(c, b) {
+    const [host, db] = await Promise.all([
+        c.api.get(`/projects/${c.project}/branches/${b.id}/endpoints`, (body) => {
+            const eps = records(obj(body, "the endpoint list").endpoints, "`endpoints`", ["id", "host"]);
+            const h = (eps.find((e) => e.type === "read_write") ?? eps[0])?.host;
+            if (!h)
+                throw new ShapeError(`branch ${b.name} has no endpoint`);
+            return h;
+        }),
+        c.api.get(`/projects/${c.project}/branches/${b.id}/databases`, (body) => {
+            const dbs = records(obj(body, "the database list").databases, "`databases`", ["name", "owner_name"]);
+            const d = dbs.find((x) => x.name === DEFAULT_DATABASE) ?? dbs[0];
+            if (!d)
+                throw new ShapeError(`branch ${b.name} has no database`);
+            return d;
+        }),
+    ]);
+    const q = new URLSearchParams({ branch_id: b.id, database_name: db.name, role_name: db.owner_name });
+    const uri = await c.api.get(`/projects/${c.project}/connection_uri?${q}`, (body) => {
+        const o = obj(body, "the connection URI");
+        if (typeof o.uri !== "string")
+            throw new ShapeError("expected `uri` to be a string");
+        return o.uri;
+    });
+    return { branch_id: b.id, connection_string: uri, host };
+}
+function parseCreated(body) {
+    const o = obj(body, "the create-branch response");
+    const branch = parseBranches([o.branch], "`branch`")[0];
+    const endpoints = Array.isArray(o.endpoints) ? records(o.endpoints, "`endpoints`", ["host"]) : [];
+    const uris = Array.isArray(o.connection_uris) ? records(o.connection_uris, "`connection_uris`", ["connection_uri"]) : [];
+    return { branch, ...(endpoints[0] ? { host: endpoints[0].host } : {}), ...(uris[0] ? { uri: uris[0].connection_uri } : {}) };
+}
+const branch = {
+    outputs: {
+        branch_id: { available: "immediate" },
+        connection_string: { available: "immediate", sensitive: true },
+        host: { available: "immediate" },
+    },
+    defaults(params, ctx) {
+        return { parent: "main", name: `sponson/${ctx.env}/${ctx.scope}`, ...params };
+    },
+    async read(actx, params) {
+        if (isPendingMarker(params.name))
+            return null;
+        const c = client(actx);
+        const name = stringParam(params, "name", "neon");
+        const found = (await listBranches(c)).find((b) => b.name === name);
+        if (!found)
+            return null;
+        return { resources: [record(found)], outputs: await outputsFor(c, found) };
+    },
+    diff(live, params) {
+        const name = params.name;
+        if (isPendingMarker(name))
+            return [{ key: "branch:(pending)", kind: "create", label: "Neon branch", before: ABSENT, after: desiredSide(name, false) }];
+        const key = branchKey(String(name));
+        const current = live?.resources.find((r) => r.key === key);
+        // A branch's identity is its name; re-parenting is not supported, so an existing branch is unchanged whatever `parent` says.
+        if (current)
+            return [{ key, kind: "unchanged", label: current.label ?? key }];
+        return [{ key, kind: "create", label: `Neon branch ${String(name)}`, before: ABSENT, after: desiredSide(name, false) }];
+    },
+    async apply(actx, params, live) {
+        assertNoPending(params, "neon");
+        const c = client(actx);
+        const name = stringParam(params, "name", "neon");
+        const key = branchKey(name);
+        if (live?.resources.some((r) => r.key === key))
+            return { resources: live.resources, outputs: live.outputs, created: [] };
+        const parentName = stringParam(params, "parent", "neon", "main");
+        const branches = await listBranches(c);
+        const parent = branches.find((b) => b.name === parentName || b.id === parentName);
+        if (!parent)
+            throw paramError("neon", `parent branch \`${parentName}\` not found in project ${c.project}`, "parent");
+        await actx.intend([key]);
+        actx.log(`create branch ${name} from ${parent.name}`);
+        let r;
+        try {
+            r = await c.api.post(`/projects/${c.project}/branches`, { branch: { name, parent_id: parent.id }, endpoints: [{ type: "read_write" }] }, parseCreated);
+        }
+        catch (e) {
+            if (!isProviderError(e, "PROVIDER_CONFLICT"))
+                throw e;
+            // It exists already (a lost response of ours, or someone else's). Not created by this call; the engine
+            // claims it when an earlier intent of ours named it.
+            const found = (await listBranches(c)).find((b) => b.name === name);
+            if (!found)
+                throw e;
+            return { resources: [record(found)], outputs: await outputsFor(c, found), created: [] };
+        }
+        // Trust the write's answer: listing right after a create may not show it yet.
+        const outputs = r.host && r.uri ? { branch_id: r.branch.id, connection_string: r.uri, host: r.host } : await outputsFor(c, r.branch);
+        return { resources: [record(r.branch)], outputs, created: [key] };
+    },
+    async destroy(actx, resources) {
+        const c = client(actx);
+        for (const r of resources)
+            await deleteIgnoringNotFound(c.api, `/projects/${c.project}/branches/${encodeURIComponent(r.id)}`);
+    },
+    /** Every branch but the project's root: anything else may be a preview branch some scope (or nobody) manages. */
+    async listScope(actx) {
+        const c = client(actx);
+        return (await listBranches(c)).filter((b) => !b.default && !b.primary).map(record);
+    },
+    /** One line per branch, naming it: the line then manages exactly that branch. */
+    adopt(resources) {
+        return resources.map((r) => {
+            const name = r.key.slice(BRANCH_PREFIX.length);
+            return { id: `db-${name}`, params: { name }, keys: [r.key] };
+        });
+    },
+};
+/**
+ * Neon: op `branch` creates a database branch per scope and outputs its connection string (sensitive). Needs
+ * `NEON_API_KEY` and `providers.neon.project`.
+ */
+export const neonAdapter = { name: "neon", ops: { branch }, about: ABOUT };
+//# sourceMappingURL=neon.js.map