@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

package/dist/esm/base-classes/services/repositories/http-api/http-api-rest-operation-reference.backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-api-rest-operation-reference.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-rest-operation-reference.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Projecting a PROVIDER operation onto an ETL read-surface spec (S3a, #331).\n *\n * This is the executable half of the convergence recorded on\n * {@link HttpApiRestOperationReferenceSchema}: a binding names an operation in the provider's own\n * catalogue, and this turns that operation plus the binding's resource-shaped half into the\n * {@link HttpApiRestOperationSpec} every REST_JSON compiler already consumes. Nothing downstream\n * changes — the compilers never learn that a reference existed.\n *\n * A pure function over data, so the interesting refusals are testable without a provider.\n */\n\nimport {\n  HttpApiRestOperationMethod,\n  type HttpApiRestOperationReference,\n  type HttpApiRestOperationSpec,\n} from '@wildo-ai/saas-models/external-data';\nimport { ExternalOperation_Classification, API_HttpMethod } from '@wildo-ai/external-connectors-models';\nimport { ProviderRestPaginationStyle, ProviderRestParameterLocation, type ProviderRestOperation } from '@wildo-ai/external-connectors-models';\n\n/** Why a referenced provider operation cannot serve an ETL read member. */\nexport enum HttpApiRestOperationReferenceRefusalKind {\n  /** The operation MUTATES the vendor; a read surface may never reference one. */\n  OPERATION_IS_A_WRITE = 'OPERATION_IS_A_WRITE',\n  /** The operation's method is outside the read-surface vocabulary (GET/POST). */\n  METHOD_NOT_READABLE = 'METHOD_NOT_READABLE',\n  /** The reference and the operation disagree about the key: named/absent/unknown parameter. */\n  KEY_PARAMETER_INCOHERENT = 'KEY_PARAMETER_INCOHERENT',\n  /** The operation's path has a token the ETL has no value for. */\n  UNSATISFIED_PATH_TOKEN = 'UNSATISFIED_PATH_TOKEN',\n}\n\nexport class HttpApiRestOperationReferenceRefusal extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly kind: HttpApiRestOperationReferenceRefusalKind;\n      readonly providerRef: string;\n      readonly providerOperationId: string;\n      readonly member: string;\n    },\n  ) {\n    super(message);\n    this.name = 'HttpApiRestOperationReferenceRefusal';\n  }\n}\n\n/** The ETL's own token for \"this resource's synthesized key\", which every REST_JSON compiler fills. */\nconst ETL_KEY_TOKEN = '{key}';\nconst PATH_TOKEN = /\\{([^}]+)\\}/g;\n\nexport interface ProjectRestOperationReferenceInput {\n  reference: HttpApiRestOperationReference;\n  operation: ProviderRestOperation;\n  providerRef: string;\n  /** Which lifecycle member is being resolved — `read` is the only key-addressed one. */\n  member: 'read' | 'list' | 'count' | 'search';\n}\n\n/**\n * Build the read-surface spec a REST_JSON compiler consumes.\n *\n * Reads only what an ETL read can honour, and refuses the rest by NAME rather than degrading:\n * every refusal here is an authoring mistake somebody must fix, and a silently degraded read\n * surface (a filter quietly dropped, a write quietly performed) is the failure this whole lane is\n * built to make impossible.\n */\nexport function projectProviderOperationOntoReadSurface(\n  input: ProjectRestOperationReferenceInput,\n): HttpApiRestOperationSpec {\n  const { reference, operation, providerRef, member } = input;\n  const refuse = (kind: HttpApiRestOperationReferenceRefusalKind, message: string): never => {\n    throw new HttpApiRestOperationReferenceRefusal(message, {\n      kind, providerRef, providerOperationId: reference.providerOperationId, member,\n    });\n  };\n\n  // A read surface that could reference a WRITE would let a LIST call delete rows, and the\n  // repository's read-only stance (ETL D3) would rest on nobody having authored it that way.\n  if (operation.classification === ExternalOperation_Classification.WRITE) {\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.OPERATION_IS_A_WRITE,\n      `The '${member}' member references provider operation '${providerRef}.${operation.operationId}', which is classified WRITE. `\n      + 'A read surface may only reference READ operations — a LIST that could mutate the target is not a read.',\n    );\n  }\n\n  if (operation.method !== API_HttpMethod.GET && operation.method !== API_HttpMethod.POST) {\n    // POST is admitted for the same reason the inline vocabulary admits it: JSON-RPC and many\n    // enterprise search endpoints are POST-shaped even for reads.\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.METHOD_NOT_READABLE,\n      `The '${member}' member references provider operation '${providerRef}.${operation.operationId}', whose method is ${operation.method}. `\n      + 'A read-surface member speaks GET or POST only.',\n    );\n  }\n\n  // ── the key token ──────────────────────────────────────────────────────────\n  const declaredPathParameters = new Set(\n    (operation.parameters ?? [])\n      .filter((parameter) => parameter.in === ProviderRestParameterLocation.PATH)\n      .map((parameter) => parameter.name),\n  );\n\n  if (member === 'read' && reference.keyParameter === undefined) {\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.KEY_PARAMETER_INCOHERENT,\n      `The 'read' member references '${providerRef}.${operation.operationId}' and declares no keyParameter — a key-addressed read has a hole `\n      + \"only this resource's synthesized key can fill, and the provider's operation names that parameter in its own vocabulary.\",\n    );\n  }\n  if (member !== 'read' && reference.keyParameter !== undefined) {\n    // Refused rather than ignored: an author who wrote it believes it does something.\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.KEY_PARAMETER_INCOHERENT,\n      `The '${member}' member declares keyParameter '${reference.keyParameter}', which only a key-addressed 'read' can use.`,\n    );\n  }\n  if (reference.keyParameter !== undefined && !declaredPathParameters.has(reference.keyParameter)) {\n    refuse(\n      HttpApiRestOperationReferenceRefusalKind.KEY_PARAMETER_INCOHERENT,\n      `The '${member}' member names keyParameter '${reference.keyParameter}', and provider operation '${providerRef}.${operation.operationId}' `\n      + `declares no PATH parameter by that name (it declares: ${[...declaredPathParameters].join(', ') || 'none'}).`,\n    );\n  }\n\n  // Rewrite the operation's own key token into the ETL's, and refuse any OTHER token: the ETL has\n  // exactly one value to supply, so a second hole would be filled with the literal `{token}` and\n  // the target would answer a confident 404 nobody could explain.\n  const pathTemplate = operation.pathTemplate.replace(PATH_TOKEN, (match, token: string) => {\n    if (token === reference.keyParameter) return ETL_KEY_TOKEN;\n    const parameter = (operation.parameters ?? []).find(\n      (candidate) => candidate.in === ProviderRestParameterLocation.PATH && candidate.name === token,\n    );\n    if (parameter?.constantValue !== undefined) return encodeURIComponent(parameter.constantValue);\n    return refuse(\n      HttpApiRestOperationReferenceRefusalKind.UNSATISFIED_PATH_TOKEN,\n      `Provider operation '${providerRef}.${operation.operationId}' has the path token '${match}', and an ETL read has no value for it `\n      + '— declare it with a constantValue on the operation, or reference an operation whose path this resource can address.',\n    );\n  });\n\n  // ── paging ─────────────────────────────────────────────────────────────────\n  // Only OFFSET paging projects: the read surface's `pagingParams` is a (limit, offset) pair, and\n  // a cursor or link style has no representation in it. Absent means the member is unpaginated\n  // here — the honest answer, since inventing an offset over a cursor API silently re-reads page\n  // one forever.\n  const pagingParams = operation.pagination?.style === ProviderRestPaginationStyle.OFFSET\n    && operation.pagination.limitParam !== undefined\n    && operation.pagination.offsetParam !== undefined\n    ? { limitParam: operation.pagination.limitParam, offsetParam: operation.pagination.offsetParam }\n    : undefined;\n\n  return {\n    method: operation.method === API_HttpMethod.POST ? HttpApiRestOperationMethod.POST : HttpApiRestOperationMethod.GET,\n    pathTemplate,\n    ...(pagingParams ? { pagingParams } : {}),\n    ...(reference.filterParams ? { filterParams: reference.filterParams } : {}),\n    ...(reference.searchParam ? { searchParam: reference.searchParam } : {}),\n    ...(operation.resultPath ? { resultPath: operation.resultPath } : {}),\n    // `jsonRpcEnvelope` is deliberately NOT projected: a provider operation has no JSON-RPC\n    // concept, so a reference can never produce one. A JSON-RPC read surface stays inline.\n  };\n}\n"]}

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.d.ts

@@ -5,7 +5,8 @@
  * rate budget. Engine-independent by design (no DI, no ErrorBuilder): the adapter maps
  * {@link HttpApiTransportError} into its ordinary error projection.
  */
-import type { HttpApiErasureOperationMethod, HttpApiRemoteCallSemantics, HttpApiRestOperationMethod } from '@wildo-ai/saas-models/external-data';
+import type { API_HttpMethod } from '@wildo-ai/external-connectors-models';
+import type { HttpApiRemoteCallSemantics } from '@wildo-ai/saas-models/external-data';
 /**
  * How a transport attempt failed — each member names a DIFFERENT remedy: TIMEOUT/NETWORK are
  * environmental (retryable), REMOTE_ERROR carries the target's own final answer, INVALID_JSON is
@@ -18,33 +19,99 @@ export declare enum HttpApiTransportFailureKind {
     INVALID_JSON = "INVALID_JSON",
     RATE_BUDGET_EXHAUSTED = "RATE_BUDGET_EXHAUSTED"
 }
-/** Minimal fetch shape — injectable so unit tests run without a network. */
+/**
+ * Minimal fetch shape — injectable so unit tests run without a network.
+ *
+ * `body` widened beyond `string` for S3a (#331): a hand-authored provider operation may upload a
+ * file (`FormData`, so the platform picks the multipart boundary — a transport that wrote its own
+ * `Content-Type` would produce a boundary the body does not use) or send raw bytes.
+ */
 export type HttpApiFetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
-    body?: string;
+    body?: string | FormData | Uint8Array;
     signal?: AbortSignal;
 }) => Promise<{
     status: number;
     ok: boolean;
     text(): Promise<string>;
 }>;
+/**
+ * How a request body is encoded on the wire. Slice 1 needed JSON alone, because every ETL call is
+ * a read; a hand-authored WRITE reaches vendors that take form bodies and file uploads, so the
+ * encoding is carried on the request rather than inferred from the method.
+ */
+export declare enum HttpApiTransportBodyEncoding {
+    JSON = "json",
+    FORM_URLENCODED = "form-urlencoded",
+    /** `FormData`; the transport sends NO `Content-Type`, so the platform sets it with its boundary. */
+    MULTIPART = "multipart",
+    /** A raw text body under a caller-declared media type. */
+    TEXT = "text",
+    /** Raw bytes under a caller-declared media type. */
+    BINARY = "binary"
+}
+/** The request body, discriminated so each encoding carries exactly what it needs. */
+export type HttpApiTransportBody = {
+    encoding: HttpApiTransportBodyEncoding.JSON;
+    value: unknown;
+} | {
+    encoding: HttpApiTransportBodyEncoding.FORM_URLENCODED;
+    value: Readonly<Record<string, string>>;
+} | {
+    encoding: HttpApiTransportBodyEncoding.MULTIPART;
+    value: FormData;
+} | {
+    encoding: HttpApiTransportBodyEncoding.TEXT;
+    value: string;
+    contentType: string;
+} | {
+    encoding: HttpApiTransportBodyEncoding.BINARY;
+    value: Uint8Array;
+    contentType: string;
+};
+/** How the RESPONSE body is decoded. */
+export declare enum HttpApiTransportResponseDecoding {
+    /** Parse as JSON; a 2xx with an unparsable body is a contract failure at the target. */
+    JSON = "json",
+    /** Keep the raw text (a CSV export, an XML document); nothing is parsed. */
+    TEXT = "text",
+    /** Read nothing — for a write whose body carries no information (a 204). */
+    NONE = "none"
+}
 export interface HttpApiTransportRequest {
     /**
-     * Read-family methods, plus the erasure family's `DELETE` — the transport is deliberately
-     * method-agnostic plumbing; WHICH methods a caller may compile is governed one layer up (the
-     * read compilers speak GET/POST, only the stance-6b erasure door speaks DELETE).
+     * The transport is deliberately method-agnostic plumbing; WHICH methods a caller may compile is
+     * governed one layer up (the read compilers speak GET/POST, the stance-6b erasure door speaks
+     * DELETE, a provider operation speaks whatever it declares). The vocabulary is
+     * `API_HttpMethod` — the one named HTTP-method source this repository already has — rather than
+     * a third list beside the two read/erasure ones.
      */
-    method: `${HttpApiRestOperationMethod}` | `${HttpApiErasureOperationMethod}`;
+    method: `${API_HttpMethod}`;
     url: string;
     headers: Record<string, string>;
-    /** JSON body, serialized by the transport (POST-shaped reads: JSON-RPC, search endpoints). */
-    jsonBody?: unknown;
+    body?: HttpApiTransportBody;
+    /** Absent = {@link HttpApiTransportResponseDecoding.JSON}, which is what every caller did before S3a. */
+    responseDecoding?: HttpApiTransportResponseDecoding;
+    /**
+     * Whether re-sending this exact request is safe. REQUIRED, and deliberately not defaulted from
+     * the method.
+     *
+     * Before S3a every call through here was a read or a delete-by-key, so retrying a timeout was
+     * always right and the policy could stay implicit. The moment a hand-authored PUT/PATCH/POST
+     * write arrives, an implicit retry duplicates it — and a default derived from the method would
+     * be wrong in BOTH directions: it would stop retrying the POST-shaped reads the ETL depends on
+     * (JSON-RPC, search endpoints), and it would happily retry a POST that charges a card. So each
+     * caller answers, and the compiler makes every framing site answer.
+     */
+    retrySafe: boolean;
 }
 export interface HttpApiTransportResponse {
     status: number;
-    /** Parsed JSON body; `undefined` for an empty body. */
+    /** Parsed JSON body; `undefined` for an empty body or a non-JSON decoding. */
     json: unknown;
+    /** Raw body text, present for {@link HttpApiTransportResponseDecoding.TEXT}. */
+    text?: string;
 }
 /**
  * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal
@@ -83,11 +150,19 @@ export declare class HttpApiRateBudget {
     tryConsume(nowMs?: number): boolean;
 }
 /**
- * Execute one remote read-family call under the binding's semantics.
+ * Execute one remote call under the caller's semantics.
+ *
+ * Retry applies to a timeout, a network error, or a retryable status (429/502/503/504) — and ONLY
+ * when the request declares itself `retrySafe`. Any other non-2xx status is a terminal remote
+ * answer and is thrown on the first attempt: retrying a 400/401/403/404 re-asks a question whose
+ * answer is final.
  *
- * Retry policy applies to IDEMPOTENT failures only: a timeout, a network error, or a retryable
- * status (429/502/503/504). Any other non-2xx status is a terminal remote answer and is thrown
- * on the first attempt — retrying a 400/401/403/404 re-asks a question whose answer is final.
+ * The `retrySafe` gate arrived with S3a (#331). Every call before it was a read or a
+ * delete-by-key, so the policy could be "retry every transient" and be right; a hand-authored
+ * write makes that policy a duplicate-submission engine. Note a 429 is gated too, and that is
+ * deliberate rather than an oversight: a 429 means the vendor did not act, but a TIMEOUT on the
+ * same request means we do not know whether it acted, and one gate that is honest about both
+ * beats two that invite the reader to work out which case they are in.
  */
 export declare function executeHttpApiTransportCall(request: HttpApiTransportRequest, semantics: Pick<HttpApiRemoteCallSemantics, 'timeoutMs' | 'retry'>, fetchImpl: HttpApiFetchLike, rateBudget?: HttpApiRateBudget): Promise<HttpApiTransportResponse>;
 //# sourceMappingURL=http-api-transport.backend.d.ts.map

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-transport.backend.d.ts","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,qCAAqC,CAAC;AAE7C;;;;GAIG;AACH,oBAAY,2BAA2B;IACrC,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,qBAAqB,0BAA0B;CAChD;AAED,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,MAAM,EAAE,GAAG,0BAA0B,EAAE,GAAG,GAAG,6BAA6B,EAAE,CAAC;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,MAAM,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,gFAAgF;QAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;KAC5C;gBARD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,gFAAgF;QAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;KAC5C;CAKJ;AAID;;;;;GAKG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAFlD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;gBAEd,oBAAoB,CAAC,EAAE,MAAM;IAE1D,mGAAmG;IACnG,UAAU,CAAC,KAAK,GAAE,MAAmB,GAAG,OAAO;CAUhD;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,uBAAuB,EAChC,SAAS,EAAE,IAAI,CAAC,0BAA0B,EAAE,WAAW,GAAG,OAAO,CAAC,EAClE,SAAS,EAAE,gBAAgB,EAC3B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAmFnC"}
+{"version":3,"file":"http-api-transport.backend.d.ts","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEtF;;;;GAIG;AACH,oBAAY,2BAA2B;IACrC,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,YAAY,iBAAiB;IAC7B,YAAY,iBAAiB;IAC7B,qBAAqB,0BAA0B;CAChD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KACE,OAAO,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH;;;;GAIG;AACH,oBAAY,4BAA4B;IACtC,IAAI,SAAS;IACb,eAAe,oBAAoB;IACnC,oGAAoG;IACpG,SAAS,cAAc;IACvB,0DAA0D;IAC1D,IAAI,SAAS;IACb,oDAAoD;IACpD,MAAM,WAAW;CAClB;AAED,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,EAAE,4BAA4B,CAAC,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC/D;IAAE,QAAQ,EAAE,4BAA4B,CAAC,eAAe,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACnG;IAAE,QAAQ,EAAE,4BAA4B,CAAC,SAAS,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GACrE;IAAE,QAAQ,EAAE,4BAA4B,CAAC,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,QAAQ,EAAE,4BAA4B,CAAC,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9F,wCAAwC;AACxC,oBAAY,gCAAgC;IAC1C,wFAAwF;IACxF,IAAI,SAAS;IACb,4EAA4E;IAC5E,IAAI,SAAS;IACb,4EAA4E;IAC5E,IAAI,SAAS;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,yGAAyG;IACzG,gBAAgB,CAAC,EAAE,gCAAgC,CAAC;IACpD;;;;;;;;;;OAUG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,OAAO,CAAC;IACd,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,MAAM,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,gFAAgF;QAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;KAC5C;gBARD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,gFAAgF;QAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;KAC5C;CAKJ;AAID;;;;;GAKG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAFlD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;gBAEd,oBAAoB,CAAC,EAAE,MAAM;IAE1D,mGAAmG;IACnG,UAAU,CAAC,KAAK,GAAE,MAAmB,GAAG,OAAO;CAUhD;AA6BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,uBAAuB,EAChC,SAAS,EAAE,IAAI,CAAC,0BAA0B,EAAE,WAAW,GAAG,OAAO,CAAC,EAClE,SAAS,EAAE,gBAAgB,EAC3B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CA+FnC"}

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.js

@@ -18,6 +18,32 @@ export var HttpApiTransportFailureKind;
     HttpApiTransportFailureKind["INVALID_JSON"] = "INVALID_JSON";
     HttpApiTransportFailureKind["RATE_BUDGET_EXHAUSTED"] = "RATE_BUDGET_EXHAUSTED";
 })(HttpApiTransportFailureKind || (HttpApiTransportFailureKind = {}));
+/**
+ * How a request body is encoded on the wire. Slice 1 needed JSON alone, because every ETL call is
+ * a read; a hand-authored WRITE reaches vendors that take form bodies and file uploads, so the
+ * encoding is carried on the request rather than inferred from the method.
+ */
+export var HttpApiTransportBodyEncoding;
+(function (HttpApiTransportBodyEncoding) {
+    HttpApiTransportBodyEncoding["JSON"] = "json";
+    HttpApiTransportBodyEncoding["FORM_URLENCODED"] = "form-urlencoded";
+    /** `FormData`; the transport sends NO `Content-Type`, so the platform sets it with its boundary. */
+    HttpApiTransportBodyEncoding["MULTIPART"] = "multipart";
+    /** A raw text body under a caller-declared media type. */
+    HttpApiTransportBodyEncoding["TEXT"] = "text";
+    /** Raw bytes under a caller-declared media type. */
+    HttpApiTransportBodyEncoding["BINARY"] = "binary";
+})(HttpApiTransportBodyEncoding || (HttpApiTransportBodyEncoding = {}));
+/** How the RESPONSE body is decoded. */
+export var HttpApiTransportResponseDecoding;
+(function (HttpApiTransportResponseDecoding) {
+    /** Parse as JSON; a 2xx with an unparsable body is a contract failure at the target. */
+    HttpApiTransportResponseDecoding["JSON"] = "json";
+    /** Keep the raw text (a CSV export, an XML document); nothing is parsed. */
+    HttpApiTransportResponseDecoding["TEXT"] = "text";
+    /** Read nothing — for a write whose body carries no information (a 204). */
+    HttpApiTransportResponseDecoding["NONE"] = "none";
+})(HttpApiTransportResponseDecoding || (HttpApiTransportResponseDecoding = {}));
 /**
  * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal
  * names the remote reality instead of a generic network error. Never carries the request
@@ -59,11 +85,46 @@ export class HttpApiRateBudget {
     }
 }
 /**
- * Execute one remote read-family call under the binding's semantics.
+ * Frame one request body: the wire bytes and the `Content-Type` that describes them.
+ *
+ * MULTIPART deliberately contributes NO header — `FormData` carries a boundary the platform
+ * generates while serializing, and a `Content-Type` written here would name a different one, so
+ * the target would parse zero parts from a body that looks well formed.
+ */
+function frameBody(body) {
+    if (body === undefined)
+        return {};
+    switch (body.encoding) {
+        case HttpApiTransportBodyEncoding.JSON:
+            return { payload: JSON.stringify(body.value), contentType: 'application/json' };
+        case HttpApiTransportBodyEncoding.FORM_URLENCODED:
+            return { payload: new URLSearchParams(body.value).toString(), contentType: 'application/x-www-form-urlencoded' };
+        case HttpApiTransportBodyEncoding.MULTIPART:
+            return { payload: body.value };
+        case HttpApiTransportBodyEncoding.TEXT:
+            return { payload: body.value, contentType: body.contentType };
+        case HttpApiTransportBodyEncoding.BINARY:
+            return { payload: body.value, contentType: body.contentType };
+        default: {
+            const exhaustiveCheck = body;
+            return exhaustiveCheck;
+        }
+    }
+}
+/**
+ * Execute one remote call under the caller's semantics.
+ *
+ * Retry applies to a timeout, a network error, or a retryable status (429/502/503/504) — and ONLY
+ * when the request declares itself `retrySafe`. Any other non-2xx status is a terminal remote
+ * answer and is thrown on the first attempt: retrying a 400/401/403/404 re-asks a question whose
+ * answer is final.
  *
- * Retry policy applies to IDEMPOTENT failures only: a timeout, a network error, or a retryable
- * status (429/502/503/504). Any other non-2xx status is a terminal remote answer and is thrown
- * on the first attempt — retrying a 400/401/403/404 re-asks a question whose answer is final.
+ * The `retrySafe` gate arrived with S3a (#331). Every call before it was a read or a
+ * delete-by-key, so the policy could be "retry every transient" and be right; a hand-authored
+ * write makes that policy a duplicate-submission engine. Note a 429 is gated too, and that is
+ * deliberate rather than an oversight: a 429 means the vendor did not act, but a TIMEOUT on the
+ * same request means we do not know whether it acted, and one gate that is honest about both
+ * beats two that invite the reader to work out which case they are in.
  */
 export async function executeHttpApiTransportCall(request, semantics, fetchImpl, rateBudget) {
     if (rateBudget && !rateBudget.tryConsume()) {
@@ -78,23 +139,33 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
         const abort = new AbortController();
         const timeout = setTimeout(() => abort.abort(), semantics.timeoutMs);
         try {
+            const framed = frameBody(request.body);
             const response = await fetchImpl(request.url, {
                 method: request.method,
-                headers: request.jsonBody === undefined
+                // The caller's own headers win: a provider that must send its own `Content-Type` for a
+                // text body has already declared it, and the framing default must not overwrite it.
+                headers: framed.contentType === undefined
                     ? request.headers
-                    : { 'Content-Type': 'application/json', ...request.headers },
-                body: request.jsonBody === undefined ? undefined : JSON.stringify(request.jsonBody),
+                    : { 'Content-Type': framed.contentType, ...request.headers },
+                body: framed.payload,
                 signal: abort.signal,
             });
             const bodyText = await response.text();
             if (!response.ok) {
                 const error = new HttpApiTransportError(`HTTP-API remote answered ${response.status} for ${request.method} ${request.url}`, { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.REMOTE_ERROR });
-                if (RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {
+                if (request.retrySafe && RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {
                     lastError = error;
                     continue;
                 }
                 throw error;
             }
+            const decoding = request.responseDecoding ?? HttpApiTransportResponseDecoding.JSON;
+            if (decoding === HttpApiTransportResponseDecoding.NONE) {
+                return { status: response.status, json: undefined };
+            }
+            if (decoding === HttpApiTransportResponseDecoding.TEXT) {
+                return { status: response.status, json: undefined, text: bodyText };
+            }
             if (bodyText.length === 0) {
                 return { status: response.status, json: undefined };
             }
@@ -108,7 +179,7 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
         }
         catch (error) {
             if (error instanceof HttpApiTransportError) {
-                if (error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {
+                if (request.retrySafe && error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {
                     lastError = error;
                     continue;
                 }
@@ -118,7 +189,7 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
             const transportError = new HttpApiTransportError(isAbort
                 ? `HTTP-API call timed out after ${semantics.timeoutMs}ms: ${request.method} ${request.url}`
                 : `HTTP-API network failure for ${request.method} ${request.url}: ${error instanceof Error ? error.message : String(error)}`, { url: request.url, method: request.method, attempts: attempt, kind: isAbort ? HttpApiTransportFailureKind.TIMEOUT : HttpApiTransportFailureKind.NETWORK });
-            if (attempt < maxAttempts) {
+            if (request.retrySafe && attempt < maxAttempts) {
                 lastError = transportError;
                 continue;
             }
@@ -128,7 +199,9 @@ export async function executeHttpApiTransportCall(request, semantics, fetchImpl,
             clearTimeout(timeout);
         }
     }
-    // Unreachable while the loop throws on its last attempt; kept for control-flow honesty.
+    // Unreachable: every path in the loop either returns or throws — a non-retry-safe request
+    // throws on its first attempt, and a retry-safe one throws on its last. Kept for control-flow
+    // honesty, and because a future edit that adds a `continue` should land somewhere honest.
     throw lastError ?? new HttpApiTransportError(`HTTP-API call failed for ${request.method} ${request.url}`, { url: request.url, method: request.method, attempts: maxAttempts, kind: HttpApiTransportFailureKind.NETWORK });
 }
 function delay(ms) {

package/dist/esm/base-classes/services/repositories/http-api/http-api-transport.backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"http-api-transport.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP transport for the HTTP-API resource repository — the ONE place a remote call leaves the\n * process, carrying the binding's declared remote-call semantics (ETL decision D10 / R15):\n * per-call timeout, bounded retry for idempotent read-family calls only, and an optional local\n * rate budget. Engine-independent by design (no DI, no ErrorBuilder): the adapter maps\n * {@link HttpApiTransportError} into its ordinary error projection.\n */\n\nimport type {\n  HttpApiErasureOperationMethod,\n  HttpApiRemoteCallSemantics,\n  HttpApiRestOperationMethod,\n} from '@wildo-ai/saas-models/external-data';\n\n/**\n * How a transport attempt failed — each member names a DIFFERENT remedy: TIMEOUT/NETWORK are\n * environmental (retryable), REMOTE_ERROR carries the target's own final answer, INVALID_JSON is\n * a contract breach at the target, RATE_BUDGET_EXHAUSTED is the binding's own local ceiling.\n */\nexport enum HttpApiTransportFailureKind {\n  TIMEOUT = 'TIMEOUT',\n  NETWORK = 'NETWORK',\n  REMOTE_ERROR = 'REMOTE_ERROR',\n  INVALID_JSON = 'INVALID_JSON',\n  RATE_BUDGET_EXHAUSTED = 'RATE_BUDGET_EXHAUSTED',\n}\n\n/** Minimal fetch shape — injectable so unit tests run without a network. */\nexport type HttpApiFetchLike = (\n  url: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n    body?: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  status: number;\n  ok: boolean;\n  text(): Promise<string>;\n}>;\n\nexport interface HttpApiTransportRequest {\n  /**\n   * Read-family methods, plus the erasure family's `DELETE` — the transport is deliberately\n   * method-agnostic plumbing; WHICH methods a caller may compile is governed one layer up (the\n   * read compilers speak GET/POST, only the stance-6b erasure door speaks DELETE).\n   */\n  method: `${HttpApiRestOperationMethod}` | `${HttpApiErasureOperationMethod}`;\n  url: string;\n  headers: Record<string, string>;\n  /** JSON body, serialized by the transport (POST-shaped reads: JSON-RPC, search endpoints). */\n  jsonBody?: unknown;\n}\n\nexport interface HttpApiTransportResponse {\n  status: number;\n  /** Parsed JSON body; `undefined` for an empty body. */\n  json: unknown;\n}\n\n/**\n * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal\n * names the remote reality instead of a generic network error. Never carries the request\n * headers (they hold credentials).\n */\nexport class HttpApiTransportError extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly url: string;\n      readonly method: string;\n      /** HTTP status of the LAST attempt; undefined when no response was received. */\n      readonly status?: number;\n      readonly attempts: number;\n      readonly kind: HttpApiTransportFailureKind;\n    },\n  ) {\n    super(message);\n    this.name = 'HttpApiTransportError';\n  }\n}\n\nconst RETRYABLE_STATUS = new Set([429, 502, 503, 504]);\n\n/**\n * A per-binding local rate budget (`maxRequestsPerMinute`) — a sliding-window counter, not a\n * fairness scheduler. When the window is full the call REFUSES immediately rather than queueing:\n * queueing inside a request lifecycle turns a rate problem into a latency problem the caller\n * cannot see (scope-down paper: refusal is the honest failure mode).\n */\nexport class HttpApiRateBudget {\n  private readonly timestamps: number[] = [];\n\n  constructor(private readonly maxRequestsPerMinute?: number) {}\n\n  /** Returns true when the call may proceed (and records it); false when the budget is exhausted. */\n  tryConsume(nowMs: number = Date.now()): boolean {\n    if (this.maxRequestsPerMinute === undefined) return true;\n    const windowStart = nowMs - 60_000;\n    while (this.timestamps.length > 0 && this.timestamps[0] <= windowStart) {\n      this.timestamps.shift();\n    }\n    if (this.timestamps.length >= this.maxRequestsPerMinute) return false;\n    this.timestamps.push(nowMs);\n    return true;\n  }\n}\n\n/**\n * Execute one remote read-family call under the binding's semantics.\n *\n * Retry policy applies to IDEMPOTENT failures only: a timeout, a network error, or a retryable\n * status (429/502/503/504). Any other non-2xx status is a terminal remote answer and is thrown\n * on the first attempt — retrying a 400/401/403/404 re-asks a question whose answer is final.\n */\nexport async function executeHttpApiTransportCall(\n  request: HttpApiTransportRequest,\n  semantics: Pick<HttpApiRemoteCallSemantics, 'timeoutMs' | 'retry'>,\n  fetchImpl: HttpApiFetchLike,\n  rateBudget?: HttpApiRateBudget,\n): Promise<HttpApiTransportResponse> {\n  if (rateBudget && !rateBudget.tryConsume()) {\n    throw new HttpApiTransportError(\n      `HTTP-API rate budget exhausted for ${request.method} ${request.url}`,\n      { url: request.url, method: request.method, attempts: 0, kind: HttpApiTransportFailureKind.RATE_BUDGET_EXHAUSTED },\n    );\n  }\n\n  const maxAttempts = semantics.retry.maxAttempts;\n  let lastError: HttpApiTransportError | undefined;\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {\n    if (attempt > 1) {\n      await delay(semantics.retry.backoffMs * (attempt - 1));\n    }\n\n    const abort = new AbortController();\n    const timeout = setTimeout(() => abort.abort(), semantics.timeoutMs);\n    try {\n      const response = await fetchImpl(request.url, {\n        method: request.method,\n        headers: request.jsonBody === undefined\n          ? request.headers\n          : { 'Content-Type': 'application/json', ...request.headers },\n        body: request.jsonBody === undefined ? undefined : JSON.stringify(request.jsonBody),\n        signal: abort.signal,\n      });\n      const bodyText = await response.text();\n\n      if (!response.ok) {\n        const error = new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.REMOTE_ERROR },\n        );\n        if (RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n\n      if (bodyText.length === 0) {\n        return { status: response.status, json: undefined };\n      }\n      try {\n        return { status: response.status, json: JSON.parse(bodyText) };\n      } catch {\n        // A 2xx with unparsable JSON is a CONTRACT failure, not a transient — never retried.\n        throw new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} with a non-JSON body for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.INVALID_JSON },\n        );\n      }\n    } catch (error) {\n      if (error instanceof HttpApiTransportError) {\n        if (error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n      const isAbort = error instanceof Error && error.name === 'AbortError';\n      const transportError = new HttpApiTransportError(\n        isAbort\n          ? `HTTP-API call timed out after ${semantics.timeoutMs}ms: ${request.method} ${request.url}`\n          : `HTTP-API network failure for ${request.method} ${request.url}: ${error instanceof Error ? error.message : String(error)}`,\n        { url: request.url, method: request.method, attempts: attempt, kind: isAbort ? HttpApiTransportFailureKind.TIMEOUT : HttpApiTransportFailureKind.NETWORK },\n      );\n      if (attempt < maxAttempts) {\n        lastError = transportError;\n        continue;\n      }\n      throw transportError;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n\n  // Unreachable while the loop throws on its last attempt; kept for control-flow honesty.\n  throw lastError ?? new HttpApiTransportError(\n    `HTTP-API call failed for ${request.method} ${request.url}`,\n    { url: request.url, method: request.method, attempts: maxAttempts, kind: HttpApiTransportFailureKind.NETWORK },\n  );\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}
+{"version":3,"file":"http-api-transport.backend.js","sourceRoot":"","sources":["../../../../../../../src/base-classes/services/repositories/http-api/http-api-transport.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HTTP transport for the HTTP-API resource repository — the ONE place a remote call leaves the\n * process, carrying the binding's declared remote-call semantics (ETL decision D10 / R15):\n * per-call timeout, bounded retry for idempotent read-family calls only, and an optional local\n * rate budget. Engine-independent by design (no DI, no ErrorBuilder): the adapter maps\n * {@link HttpApiTransportError} into its ordinary error projection.\n */\n\nimport type { API_HttpMethod } from '@wildo-ai/external-connectors-models';\nimport type { HttpApiRemoteCallSemantics } from '@wildo-ai/saas-models/external-data';\n\n/**\n * How a transport attempt failed — each member names a DIFFERENT remedy: TIMEOUT/NETWORK are\n * environmental (retryable), REMOTE_ERROR carries the target's own final answer, INVALID_JSON is\n * a contract breach at the target, RATE_BUDGET_EXHAUSTED is the binding's own local ceiling.\n */\nexport enum HttpApiTransportFailureKind {\n  TIMEOUT = 'TIMEOUT',\n  NETWORK = 'NETWORK',\n  REMOTE_ERROR = 'REMOTE_ERROR',\n  INVALID_JSON = 'INVALID_JSON',\n  RATE_BUDGET_EXHAUSTED = 'RATE_BUDGET_EXHAUSTED',\n}\n\n/**\n * Minimal fetch shape — injectable so unit tests run without a network.\n *\n * `body` widened beyond `string` for S3a (#331): a hand-authored provider operation may upload a\n * file (`FormData`, so the platform picks the multipart boundary — a transport that wrote its own\n * `Content-Type` would produce a boundary the body does not use) or send raw bytes.\n */\nexport type HttpApiFetchLike = (\n  url: string,\n  init: {\n    method: string;\n    headers: Record<string, string>;\n    body?: string | FormData | Uint8Array;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  status: number;\n  ok: boolean;\n  text(): Promise<string>;\n}>;\n\n/**\n * How a request body is encoded on the wire. Slice 1 needed JSON alone, because every ETL call is\n * a read; a hand-authored WRITE reaches vendors that take form bodies and file uploads, so the\n * encoding is carried on the request rather than inferred from the method.\n */\nexport enum HttpApiTransportBodyEncoding {\n  JSON = 'json',\n  FORM_URLENCODED = 'form-urlencoded',\n  /** `FormData`; the transport sends NO `Content-Type`, so the platform sets it with its boundary. */\n  MULTIPART = 'multipart',\n  /** A raw text body under a caller-declared media type. */\n  TEXT = 'text',\n  /** Raw bytes under a caller-declared media type. */\n  BINARY = 'binary',\n}\n\n/** The request body, discriminated so each encoding carries exactly what it needs. */\nexport type HttpApiTransportBody =\n  | { encoding: HttpApiTransportBodyEncoding.JSON; value: unknown }\n  | { encoding: HttpApiTransportBodyEncoding.FORM_URLENCODED; value: Readonly<Record<string, string>> }\n  | { encoding: HttpApiTransportBodyEncoding.MULTIPART; value: FormData }\n  | { encoding: HttpApiTransportBodyEncoding.TEXT; value: string; contentType: string }\n  | { encoding: HttpApiTransportBodyEncoding.BINARY; value: Uint8Array; contentType: string };\n\n/** How the RESPONSE body is decoded. */\nexport enum HttpApiTransportResponseDecoding {\n  /** Parse as JSON; a 2xx with an unparsable body is a contract failure at the target. */\n  JSON = 'json',\n  /** Keep the raw text (a CSV export, an XML document); nothing is parsed. */\n  TEXT = 'text',\n  /** Read nothing — for a write whose body carries no information (a 204). */\n  NONE = 'none',\n}\n\nexport interface HttpApiTransportRequest {\n  /**\n   * The transport is deliberately method-agnostic plumbing; WHICH methods a caller may compile is\n   * governed one layer up (the read compilers speak GET/POST, the stance-6b erasure door speaks\n   * DELETE, a provider operation speaks whatever it declares). The vocabulary is\n   * `API_HttpMethod` — the one named HTTP-method source this repository already has — rather than\n   * a third list beside the two read/erasure ones.\n   */\n  method: `${API_HttpMethod}`;\n  url: string;\n  headers: Record<string, string>;\n  body?: HttpApiTransportBody;\n  /** Absent = {@link HttpApiTransportResponseDecoding.JSON}, which is what every caller did before S3a. */\n  responseDecoding?: HttpApiTransportResponseDecoding;\n  /**\n   * Whether re-sending this exact request is safe. REQUIRED, and deliberately not defaulted from\n   * the method.\n   *\n   * Before S3a every call through here was a read or a delete-by-key, so retrying a timeout was\n   * always right and the policy could stay implicit. The moment a hand-authored PUT/PATCH/POST\n   * write arrives, an implicit retry duplicates it — and a default derived from the method would\n   * be wrong in BOTH directions: it would stop retrying the POST-shaped reads the ETL depends on\n   * (JSON-RPC, search endpoints), and it would happily retry a POST that charges a card. So each\n   * caller answers, and the compiler makes every framing site answer.\n   */\n  retrySafe: boolean;\n}\n\nexport interface HttpApiTransportResponse {\n  status: number;\n  /** Parsed JSON body; `undefined` for an empty body or a non-JSON decoding. */\n  json: unknown;\n  /** Raw body text, present for {@link HttpApiTransportResponseDecoding.TEXT}. */\n  text?: string;\n}\n\n/**\n * Every transport failure carries WHAT was attempted and HOW OFTEN, so the adapter's refusal\n * names the remote reality instead of a generic network error. Never carries the request\n * headers (they hold credentials).\n */\nexport class HttpApiTransportError extends Error {\n  constructor(\n    message: string,\n    public readonly detail: {\n      readonly url: string;\n      readonly method: string;\n      /** HTTP status of the LAST attempt; undefined when no response was received. */\n      readonly status?: number;\n      readonly attempts: number;\n      readonly kind: HttpApiTransportFailureKind;\n    },\n  ) {\n    super(message);\n    this.name = 'HttpApiTransportError';\n  }\n}\n\nconst RETRYABLE_STATUS = new Set([429, 502, 503, 504]);\n\n/**\n * A per-binding local rate budget (`maxRequestsPerMinute`) — a sliding-window counter, not a\n * fairness scheduler. When the window is full the call REFUSES immediately rather than queueing:\n * queueing inside a request lifecycle turns a rate problem into a latency problem the caller\n * cannot see (scope-down paper: refusal is the honest failure mode).\n */\nexport class HttpApiRateBudget {\n  private readonly timestamps: number[] = [];\n\n  constructor(private readonly maxRequestsPerMinute?: number) {}\n\n  /** Returns true when the call may proceed (and records it); false when the budget is exhausted. */\n  tryConsume(nowMs: number = Date.now()): boolean {\n    if (this.maxRequestsPerMinute === undefined) return true;\n    const windowStart = nowMs - 60_000;\n    while (this.timestamps.length > 0 && this.timestamps[0] <= windowStart) {\n      this.timestamps.shift();\n    }\n    if (this.timestamps.length >= this.maxRequestsPerMinute) return false;\n    this.timestamps.push(nowMs);\n    return true;\n  }\n}\n\n/**\n * Frame one request body: the wire bytes and the `Content-Type` that describes them.\n *\n * MULTIPART deliberately contributes NO header — `FormData` carries a boundary the platform\n * generates while serializing, and a `Content-Type` written here would name a different one, so\n * the target would parse zero parts from a body that looks well formed.\n */\nfunction frameBody(body: HttpApiTransportBody | undefined): { payload?: string | FormData | Uint8Array; contentType?: string } {\n  if (body === undefined) return {};\n  switch (body.encoding) {\n    case HttpApiTransportBodyEncoding.JSON:\n      return { payload: JSON.stringify(body.value), contentType: 'application/json' };\n    case HttpApiTransportBodyEncoding.FORM_URLENCODED:\n      return { payload: new URLSearchParams(body.value as Record<string, string>).toString(), contentType: 'application/x-www-form-urlencoded' };\n    case HttpApiTransportBodyEncoding.MULTIPART:\n      return { payload: body.value };\n    case HttpApiTransportBodyEncoding.TEXT:\n      return { payload: body.value, contentType: body.contentType };\n    case HttpApiTransportBodyEncoding.BINARY:\n      return { payload: body.value, contentType: body.contentType };\n    default: {\n      const exhaustiveCheck: never = body;\n      return exhaustiveCheck;\n    }\n  }\n}\n\n/**\n * Execute one remote call under the caller's semantics.\n *\n * Retry applies to a timeout, a network error, or a retryable status (429/502/503/504) — and ONLY\n * when the request declares itself `retrySafe`. Any other non-2xx status is a terminal remote\n * answer and is thrown on the first attempt: retrying a 400/401/403/404 re-asks a question whose\n * answer is final.\n *\n * The `retrySafe` gate arrived with S3a (#331). Every call before it was a read or a\n * delete-by-key, so the policy could be \"retry every transient\" and be right; a hand-authored\n * write makes that policy a duplicate-submission engine. Note a 429 is gated too, and that is\n * deliberate rather than an oversight: a 429 means the vendor did not act, but a TIMEOUT on the\n * same request means we do not know whether it acted, and one gate that is honest about both\n * beats two that invite the reader to work out which case they are in.\n */\nexport async function executeHttpApiTransportCall(\n  request: HttpApiTransportRequest,\n  semantics: Pick<HttpApiRemoteCallSemantics, 'timeoutMs' | 'retry'>,\n  fetchImpl: HttpApiFetchLike,\n  rateBudget?: HttpApiRateBudget,\n): Promise<HttpApiTransportResponse> {\n  if (rateBudget && !rateBudget.tryConsume()) {\n    throw new HttpApiTransportError(\n      `HTTP-API rate budget exhausted for ${request.method} ${request.url}`,\n      { url: request.url, method: request.method, attempts: 0, kind: HttpApiTransportFailureKind.RATE_BUDGET_EXHAUSTED },\n    );\n  }\n\n  const maxAttempts = semantics.retry.maxAttempts;\n  let lastError: HttpApiTransportError | undefined;\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {\n    if (attempt > 1) {\n      await delay(semantics.retry.backoffMs * (attempt - 1));\n    }\n\n    const abort = new AbortController();\n    const timeout = setTimeout(() => abort.abort(), semantics.timeoutMs);\n    try {\n      const framed = frameBody(request.body);\n      const response = await fetchImpl(request.url, {\n        method: request.method,\n        // The caller's own headers win: a provider that must send its own `Content-Type` for a\n        // text body has already declared it, and the framing default must not overwrite it.\n        headers: framed.contentType === undefined\n          ? request.headers\n          : { 'Content-Type': framed.contentType, ...request.headers },\n        body: framed.payload,\n        signal: abort.signal,\n      });\n      const bodyText = await response.text();\n\n      if (!response.ok) {\n        const error = new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.REMOTE_ERROR },\n        );\n        if (request.retrySafe && RETRYABLE_STATUS.has(response.status) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n\n      const decoding = request.responseDecoding ?? HttpApiTransportResponseDecoding.JSON;\n      if (decoding === HttpApiTransportResponseDecoding.NONE) {\n        return { status: response.status, json: undefined };\n      }\n      if (decoding === HttpApiTransportResponseDecoding.TEXT) {\n        return { status: response.status, json: undefined, text: bodyText };\n      }\n      if (bodyText.length === 0) {\n        return { status: response.status, json: undefined };\n      }\n      try {\n        return { status: response.status, json: JSON.parse(bodyText) };\n      } catch {\n        // A 2xx with unparsable JSON is a CONTRACT failure, not a transient — never retried.\n        throw new HttpApiTransportError(\n          `HTTP-API remote answered ${response.status} with a non-JSON body for ${request.method} ${request.url}`,\n          { url: request.url, method: request.method, status: response.status, attempts: attempt, kind: HttpApiTransportFailureKind.INVALID_JSON },\n        );\n      }\n    } catch (error) {\n      if (error instanceof HttpApiTransportError) {\n        if (request.retrySafe && error.detail.kind === HttpApiTransportFailureKind.REMOTE_ERROR && RETRYABLE_STATUS.has(error.detail.status ?? 0) && attempt < maxAttempts) {\n          lastError = error;\n          continue;\n        }\n        throw error;\n      }\n      const isAbort = error instanceof Error && error.name === 'AbortError';\n      const transportError = new HttpApiTransportError(\n        isAbort\n          ? `HTTP-API call timed out after ${semantics.timeoutMs}ms: ${request.method} ${request.url}`\n          : `HTTP-API network failure for ${request.method} ${request.url}: ${error instanceof Error ? error.message : String(error)}`,\n        { url: request.url, method: request.method, attempts: attempt, kind: isAbort ? HttpApiTransportFailureKind.TIMEOUT : HttpApiTransportFailureKind.NETWORK },\n      );\n      if (request.retrySafe && attempt < maxAttempts) {\n        lastError = transportError;\n        continue;\n      }\n      throw transportError;\n    } finally {\n      clearTimeout(timeout);\n    }\n  }\n\n  // Unreachable: every path in the loop either returns or throws — a non-retry-safe request\n  // throws on its first attempt, and a retry-safe one throws on its last. Kept for control-flow\n  // honesty, and because a future edit that adds a `continue` should land somewhere honest.\n  throw lastError ?? new HttpApiTransportError(\n    `HTTP-API call failed for ${request.method} ${request.url}`,\n    { url: request.url, method: request.method, attempts: maxAttempts, kind: HttpApiTransportFailureKind.NETWORK },\n  );\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}

package/dist/esm/base-classes/services/repositories/infrastructure-tier-contract.backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"infrastructure-tier-contract.backend.d.ts","sourceRoot":"","sources":["../../../../../../src/base-classes/services/repositories/infrastructure-tier-contract.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;;;;;GAOG;AACH,oBAAY,kBAAkB;IAC5B,gGAAgG;IAChG,eAAe,oCAAoC;IACnD,gFAAgF;IAChF,SAAS,8BAA8B;IACvC,oFAAoF;IACpF,oBAAoB,sBAAsB;IAC1C,sEAAsE;IACtE,eAAe,oCAAoC;IACnD,qFAAqF;IACrF,WAAW,gCAAgC;IAC3C,+DAA+D;IAC/D,WAAW,gCAAgC;IAC3C,yCAAyC;IACzC,uBAAuB,0BAA0B;IACjD,iEAAiE;IACjE,sBAAsB,yBAAyB;IAC/C,wCAAwC;IACxC,sBAAsB,yBAAyB;CAChD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oBAAY,iCAAiC;IAC3C;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;;;;;;;;OAWG;IACH,cAAc,kBAAkB;IAChC;;;;OAIG;IACH,iBAAiB,qBAAqB;IACtC;;;;;OAKG;IACH,cAAc,kBAAkB;IAChC;;;;OAIG;IACH,kBAAkB,qBAAqB;IACvC;;;OAGG;IACH,WAAW,eAAe;IAC1B;;;;;;;;;OASG;IACH,yBAAyB,6BAA6B;IACtD;;;;OAIG;IACH,kBAAkB,sBAAsB;CACzC;AAED,oBAAY,4BAA4B;IACtC,6CAA6C;IAC7C,SAAS,cAAc;IACvB,sFAAsF;IACtF,MAAM,WAAW;IACjB,mGAAmG;IACnG,cAAc,mBAAmB;CAClC;AAED;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GACxC;IAAE,OAAO,EAAE,4BAA4B,CAAC,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,OAAO,EAAE,4BAA4B,CAAC,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC7F;IAAE,OAAO,EAAE,4BAA4B,CAAC,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAoI7E,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAC/C,kBAAkB,EAClB,MAAM,CAAC,iCAAiC,EAAE,gCAAgC,CAAC,CAyR5E,CAAC;AAIF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8CAA8C,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3F,CAAC;AAEF;;;;;;;;GAQG;AACH,oBAAY,sCAAsC;IAChD,YAAY,gBAAgB;IAC5B,4BAA4B,+BAA+B;CAC5D;AAED,eAAO,MAAM,0CAA0C,EAAE,MAAM,CAC7D,sCAAsC,EACtC,MAAM,CAcP,CAAC"}
+{"version":3,"file":"infrastructure-tier-contract.backend.d.ts","sourceRoot":"","sources":["../../../../../../src/base-classes/services/repositories/infrastructure-tier-contract.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH;;;;;;;GAOG;AACH,oBAAY,kBAAkB;IAC5B,gGAAgG;IAChG,eAAe,oCAAoC;IACnD,gFAAgF;IAChF,SAAS,8BAA8B;IACvC,oFAAoF;IACpF,oBAAoB,sBAAsB;IAC1C,sEAAsE;IACtE,eAAe,oCAAoC;IACnD,qFAAqF;IACrF,WAAW,gCAAgC;IAC3C,+DAA+D;IAC/D,WAAW,gCAAgC;IAC3C,yCAAyC;IACzC,uBAAuB,0BAA0B;IACjD,iEAAiE;IACjE,sBAAsB,yBAAyB;IAC/C,wCAAwC;IACxC,sBAAsB,yBAAyB;CAChD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oBAAY,iCAAiC;IAC3C;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;;;;;;;;;OAWG;IACH,cAAc,kBAAkB;IAChC;;;;OAIG;IACH,iBAAiB,qBAAqB;IACtC;;;;;OAKG;IACH,cAAc,kBAAkB;IAChC;;;;OAIG;IACH,kBAAkB,qBAAqB;IACvC;;;OAGG;IACH,WAAW,eAAe;IAC1B;;;;;;;;;OASG;IACH,yBAAyB,6BAA6B;IACtD;;;;OAIG;IACH,kBAAkB,sBAAsB;CACzC;AAED,oBAAY,4BAA4B;IACtC,6CAA6C;IAC7C,SAAS,cAAc;IACvB,sFAAsF;IACtF,MAAM,WAAW;IACjB,mGAAmG;IACnG,cAAc,mBAAmB;CAClC;AAED;;;;GAIG;AACH,MAAM,MAAM,gCAAgC,GACxC;IAAE,OAAO,EAAE,4BAA4B,CAAC,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,OAAO,EAAE,4BAA4B,CAAC,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC7F;IAAE,OAAO,EAAE,4BAA4B,CAAC,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA4I7E,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAC/C,kBAAkB,EAClB,MAAM,CAAC,iCAAiC,EAAE,gCAAgC,CAAC,CAyR5E,CAAC;AAIF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8CAA8C,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM3F,CAAC;AAEF;;;;;;;;GAQG;AACH,oBAAY,sCAAsC;IAChD,YAAY,gBAAgB;IAC5B,4BAA4B,+BAA+B;CAC5D;AAED,eAAO,MAAM,0CAA0C,EAAE,MAAM,CAC7D,sCAAsC,EACtC,MAAM,CAcP,CAAC"}

package/dist/esm/base-classes/services/repositories/infrastructure-tier-contract.backend.js

@@ -251,7 +251,15 @@ const SCHEMA_VALIDATION_WAIVED_PRE_BUILT_WRITE = {
     compensation: 'Shape only, never values: `describeGuardedMutationInexpressibility` refuses a mutation that '
         + 'cannot be expressed on every adapter. Nothing checks what the mutation SAYS.',
 };
-/** Every door but {@link InfrastructureDoor.COUNT_DOCUMENTS} accepts `RepositoryOptions` and forwards them unchanged. */
+/**
+ * The plain reason SEVEN doors give: they accept `RepositoryOptions` and forward them unchanged.
+ *
+ * ALL EIGHT doors do that now. {@link InfrastructureDoor.COUNT_DOCUMENTS} states its own cell rather
+ * than reusing this one because it has a longer story to tell — it was the one door that accepted no
+ * options at all (issue #104), and its cell records that rather than letting the repair erase it.
+ * This comment previously read "every door BUT COUNT_DOCUMENTS accepts them", which was true when it
+ * was written and became a false description of the tier the moment the door was fixed.
+ */
 const TRANSACTION_PARTICIPATION_PRESERVED = {
     posture: PRESERVED,
     how: 'Accepts `RepositoryOptions` and forwards them to the primitive, so a caller already inside a '