@sponson/adapters 0.0.0-stage → 0.5.0

package/dist/http-adapter-spec.d.ts

@@ -0,0 +1,216 @@
+/**
+ * The generic `http` adapter's plan syntax, parsed and checked: the per-API provider block, the params of
+ * `http.resource` and `http.list_item`, JSON pointers and path placeholders. Pure: no I/O. Every malformed spec is
+ * a PARAM_INVALID (or PLAN_INVALID for the provider block) naming the field at fault. See ADR 0017 and
+ * docs/plan-format.md (`http.resource`, `http.list_item`).
+ */
+import { type OutputSpec } from "@sponson/core";
+import { type Auth } from "./http-adapter-auth.js";
+import { type GraphqlSpec } from "./http-adapter-graphql.js";
+export type { Auth } from "./http-adapter-auth.js";
+export declare const ADAPTER = "http";
+/** A JSON pointer's reference tokens. `""` is the whole document. */
+export declare function pointerTokens(pointer: string): string[];
+/** A field as the plan writes it: `name` (a top-level field) or a JSON pointer `/config/url`. */
+export declare function fieldTokens(field: string): string[];
+/** The value at `tokens` in `doc`, or undefined. */
+export declare function at(doc: unknown, tokens: string[]): unknown;
+/** A copy of `doc` (an object) with `value` set at `tokens`, creating objects on the way. */
+export declare function setAt(doc: Record<string, unknown>, tokens: string[], value: unknown): Record<string, unknown>;
+/** Objects merged recursively (`b` wins); anything else is replaced by `b`. */
+export declare function deepMerge(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown>;
+/** The request body that sets every field of `fields` (names or pointers), skipping `skip`. */
+export declare function bodyOf(fields: Record<string, unknown>, skip?: (v: unknown) => boolean): Record<string, unknown>;
+/** `item` reduced to the declared fields, in the one canonical form both hashes and diffs use. Absent is null. */
+export declare function projection(item: unknown, fields: string[]): Record<string, unknown>;
+/** The hash of a resource's declared state: `sha256(canonicalJson(projection))`. */
+export declare function stateHash(state: unknown): string;
+/** True when the value is `{ keep: true }`'s marker. */
+export declare function isKeep(v: unknown): boolean;
+/** The first pending or secret marker anywhere in `v`, if any. */
+export declare function firstMarker(v: unknown): string | undefined;
+/** The `{name}` and `{+name}` placeholders of a path, by name. */
+export declare function placeholders(path: string): string[];
+/**
+ * `path` with `{id}` and every `{var}` substituted (URI-encoded; `{+var}` keeps `/` and `:`); undefined when a value
+ * is not known yet (a pending reference).
+ */
+export declare function fillPath(path: string, vars: Record<string, unknown>, id?: string): string | undefined;
+/** One API's configuration, from `providers.http.<api>`. */
+export interface ApiConfig {
+    baseUrl: string;
+    baseUrlEnv?: string;
+    auth: Auth;
+    headers: Record<string, string>;
+    encoding: "json" | "form" | "xml";
+    /** A versioned media type sent as `Accept` and as the `Content-Type` of JSON bodies (Atlas `application/vnd.atlas.2023-01-01+json`). */
+    mediaType?: string;
+    /** The API is a production system: lines through it need Sponson's approval (`writesEnvironment`). */
+    production: boolean;
+    /**
+     * Credentials this API refuses: a value starting with one of `prefixes` (Stripe's `sk_live_`) is PROVIDER_AUTH
+     * before any request, unless the variable `unlessEnv` is `1` or `true`.
+     */
+    refuse?: {
+        prefixes: string[];
+        unlessEnv: string;
+    };
+}
+/**
+ * `OpSpec.writesEnvironment` for both ops: `production` when the line's API block says `production: true` (a live
+ * Stripe account, a production tenant), so the run needs approval whatever its environment; otherwise not
+ * environment-specific. `provider` is the block `apiBlock` narrowed to, already checked.
+ */
+export declare function apiEnvironment(_params: Record<string, unknown>, _ctx: unknown, provider?: Record<string, unknown>): "production" | null;
+/**
+ * One API block, checked. `where` names it in messages (`providers.http.statsig`). `authOptional`: a block without
+ * `auth` sends no credential (the `manual` adapter's verify requests to public endpoints); the `http` adapter's
+ * blocks always need one.
+ */
+export declare function parseApi(block: Record<string, unknown>, where: string, opts?: {
+    authOptional?: boolean;
+}): ApiConfig;
+/**
+ * `OpSpec.providerFor` for both ops: the `providers.http.<api>` block the line's `api` names, checked. Lines of
+ * different APIs therefore have independent ledger identities.
+ */
+export declare function apiBlock(block: Record<string, unknown>, params: Record<string, unknown>): Record<string, unknown>;
+/** What `destroy` does with what Sponson created: remove it (the default), or leave it in place. */
+export type DestroyMode = "delete" | "keep";
+/**
+ * One request of a spec: method and path (placeholders unfilled), the extra body it sends, its media type, the
+ * headers it sends (values may be references until apply), and whether the declared `fields` go in its body
+ * (`send_fields: false` when the request carries them elsewhere, such as in headers); or a GraphQL request (`path`
+ * is then "", the endpoint being the API's base URL).
+ */
+export interface RequestSpec {
+    method: string;
+    path: string;
+    body: Record<string, unknown>;
+    contentType?: string;
+    headers: Record<string, unknown>;
+    sendFields: boolean;
+    graphql?: GraphqlSpec;
+}
+/** How a resource is located by natural key: a list, the array in it, and the fields that must match. */
+export interface FindSpec {
+    /** "" for a GraphQL find. */
+    path: string;
+    graphql?: GraphqlSpec;
+    listPath: string;
+    match: Record<string, unknown>;
+    /** Pointer to the next page's cursor in a list response, and the query parameter that sends it back. */
+    next?: {
+        path: string;
+        param: string;
+    };
+}
+/**
+ * Declared output: a pointer into the object, whether it must never be shown, and whether the provider reveals it
+ * only in the answer that creates the object (`once`, ADR 0018: an API key's token, a signing secret).
+ */
+export interface OutputDecl {
+    path: string;
+    sensitive: boolean;
+    once: boolean;
+}
+/** `http.resource` params, checked. Values may still be markers. */
+export interface ResourceSpec {
+    api: string;
+    vars: Record<string, unknown>;
+    /** The line's own credential value (`credential`), replacing the API block's variable; a marker while pending. */
+    credential?: unknown;
+    /** `locate`: the create's answer is not the object (the parent, an acknowledgement); find it afterwards. */
+    create: RequestSpec & {
+        idempotencyKey: boolean;
+        locate: boolean;
+    };
+    read?: {
+        path: string;
+        graphql?: GraphqlSpec;
+    };
+    find?: FindSpec;
+    update?: RequestSpec;
+    /**
+     * How the object is removed. A `POST` with a `body` archives instead of deleting (Stripe prices cannot be deleted,
+     * only set `active: false`); the body is part of the record id, so destroy needs nothing but the ledger. Or a
+     * GraphQL mutation.
+     */
+    delete: {
+        method: string;
+        path: string;
+        body?: Record<string, unknown>;
+        graphql?: GraphqlSpec;
+    };
+    destroy: DestroyMode;
+    itemPath: string;
+    idPath: string;
+    fields: Record<string, unknown>;
+    outputs: Record<string, OutputDecl>;
+    /** Statuses that mean "it exists already" on create (besides 409 and the client's conflict wording). */
+    existsStatus: number[];
+    /** Statuses that mean "it is gone" on read and delete (besides 404). */
+    goneStatus: number[];
+}
+/** A request's headers with their resolved values, as strings; PARAM_INVALID for a value that is not a scalar. */
+export declare function requestHeaders(req: RequestSpec, param: string): Record<string, string>;
+/** `http.resource` params, checked; PARAM_INVALID naming the field otherwise. */
+export declare function parseResource(line: Record<string, unknown>): ResourceSpec;
+/**
+ * `OpSpec.credentialInputs` for both ops: the line's `credential`, which the engine checks is a masked reference.
+ * Its own rules (its form, `destroy: keep`) are checked here too, so a wrong line fails before any request.
+ */
+export declare function credentialInputs(kind: "resource" | "list_item"): (params: Record<string, unknown>) => string[];
+/** The outputs one `http.resource` line declares: always `id`, plus its `outputs` (`once` ones as in ADR 0018). */
+export declare function resourceOutputs(line: Record<string, unknown>): Record<string, OutputSpec>;
+/**
+ * How the parent holds its items: a JSON array (`array`), one string of values joined by `separator`
+ * (`delimited`, such as a comma-separated allow-list), or a map of name to value (`map`, such as config vars,
+ * where writing `null` for a name deletes it).
+ */
+export type ListShape = "array" | "delimited" | "map";
+/**
+ * What a write of the parent sends besides the collection: nothing (`field`; a keyed map's one entry, as a merge
+ * patch), nothing but the whole collection (`collection`; a keyed map too, for an API that replaces the map it is
+ * sent), the whole object read just before (`parent`), or the listed fields of it (names or pointers), for a
+ * replace that resets what it is not sent.
+ */
+export type ParentSend = "field" | "parent" | "collection" | string[];
+/** `http.list_item` params, checked. */
+export interface ListItemSpec {
+    api: string;
+    vars: Record<string, unknown>;
+    /** The line's own credential value (`credential`), replacing the API block's variable; a marker while pending. */
+    credential?: unknown;
+    /**
+     * `itemPath`: where the parent object is in the read answer (`/feature` for `{ feature: {...} }`); default the whole
+     * body. `ifMissing: empty`: a 404 parent reads as an empty collection; `whenEmpty: delete`: an empty collection is
+     * removed with DELETE instead of written. `readMethod: POST`: the parent is read with a POST without a body (an
+     * Azure Resource Manager list action such as `listAppSettings`), which changes nothing. `writeListPath`: where a
+     * write puts the collection, when the API names it otherwise than its read (Kinde reads `{ redirect_urls }` and replaces with `{ urls }`); default `list_path`.
+     */
+    parent: {
+        path: string;
+        readPath: string;
+        readMethod: "GET" | "POST";
+        method: string;
+        send: ParentSend;
+        itemPath: string;
+        contentType?: string;
+        ifMissing: "error" | "empty";
+        whenEmpty: "write" | "delete";
+        writeListPath?: string;
+    };
+    listPath: string;
+    shape: ListShape;
+    separator: string;
+    /** The item: a value or a map (`array`), a string (`delimited`), the entry's name (`map`). */
+    item: unknown;
+    /** For map items of an `array`: the field that identifies an item in the list. */
+    keyField?: string;
+    /** For `map`: the entry's value. */
+    value?: unknown;
+    destroy: DestroyMode;
+}
+/** `http.list_item` params, checked; PARAM_INVALID naming the field otherwise. */
+export declare function parseListItem(line: Record<string, unknown>): ListItemSpec;