@syndroo/sdk 0.4.0-rc.1 → 0.7.0

package/dist/http.d.ts

@@ -1,45 +1,101 @@
 /**
- * The single HTTP transport used by the SDK.
+ * HTTP transport for `@syndroo/sdk`.
  *
- * Invariants this module enforces for every request:
+ * Scope, deliberately narrow:
  *
- * - exactly one network request per call; the SDK never retries a write,
- *   because a retry without a stable idempotency key can duplicate a post;
- * - redirects are not followed, so the `Authorization` header can never reach
- *   a redirect target;
- * - every request is bounded by a finite deadline;
- * - the response body is read with a size limit, so an oversized or hostile
- *   response cannot exhaust the caller's memory;
- * - no logging, so credentials and content never reach stdout or stderr.
+ * - `POST /v1/connect`, `POST /v1/publish`, `POST /v1/status` only. There is no
+ *   GET business route, no health probe and no CRUD family.
+ * - The bearer secret is required and travels only in the `Authorization`
+ *   header. It is never placed in a URL, a query string or an error.
+ * - The base URL is checked before any socket is opened. Credentials/userinfo,
+ *   a query and a fragment are rejected, and plain HTTP is accepted only for a
+ *   loopback host, because a remote cleartext endpoint would expose the bearer
+ *   secret to the network.
+ * - Redirects are never followed (`redirect: "manual"`). Following one would
+ *   forward the `Authorization` header to an origin the caller never chose.
+ * - A request body is bounded and validated by the generated validator (64 KiB);
+ *   a response is read with a hard 1 MiB cap while streaming, decoded as strict
+ *   UTF-8 and parsed by the generated bounded parser, then validated as an
+ *   envelope whose `operation` must match the call.
+ * - Transport retries reuse one idempotency key. A valid envelope is never
+ *   retried, whatever its business result says: `failed`, `partial` and
+ *   `unknown` are protocol successes, not transport errors.
  */
-export declare const DEFAULT_TIMEOUT_MS = 30000;
-export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
-export declare const MIN_MAX_RESPONSE_BYTES = 1024;
-export interface TransportConfig {
+import { type WireName } from "./generated/validators.js";
+import type { FetchLike, WireOperation } from "./types.js";
+/** Protocol and transport bounds. Changing one is an API decision. */
+export declare const LIMITS: Readonly<{
+    /** Largest request body the wire protocol accepts. */
+    maxRequestBytes: 65536;
+    /** Largest response body the SDK will buffer. */
+    maxResponseBytes: 1048576;
+    /** Default per-request deadline. */
+    defaultTimeoutMs: 30000;
+    /** Smallest accepted per-request deadline. */
+    minTimeoutMs: 1;
+    /** Largest per-request deadline the protocol allows. */
+    maxTimeoutMs: 120000;
+    /** Largest number of transport retries the protocol allows. */
+    maxTransportRetries: 2;
+    /** Longest accepted caller-supplied idempotency key. */
+    maxIdempotencyKeyLength: 128;
+}>;
+export type TransportConfig = {
     baseUrl: string;
     apiKey: string;
-    timeoutMs: number;
-    maxResponseBytes: number;
-}
-export interface TransportRequest {
-    method: "GET" | "POST";
-    path: string;
-    query?: Record<string, string> | undefined;
-    json?: unknown;
-    idempotencyKey?: string | undefined;
-    /** `false` for unauthenticated endpoints such as `/health`. */
-    authenticated?: boolean | undefined;
-    signal?: AbortSignal | undefined;
-    timeoutMs?: number | undefined;
-}
-export interface TransportResponse {
-    status: number;
+    fetch: FetchLike;
+};
+/** One prepared transport call. */
+export type TransportRequest = {
+    operation: WireOperation;
+    /** Generated wire name of the request body, used for validation. */
+    wireName: WireName;
     body: unknown;
-}
-export declare function sendRequest(config: TransportConfig, request: TransportRequest): Promise<TransportResponse>;
+    idempotencyKey?: string;
+    timeoutMs: number;
+    transportRetries: number;
+    signal?: AbortSignal;
+};
+/** The loopback hosts that may be reached over plain HTTP. */
+export declare function isLoopbackHostname(hostname: string): boolean;
 /**
- * Node keeps the process alive for a pending timer. An SDK call must not pin a
- * CLI process open after its response or its deadline.
+ * Validate a base URL, or throw a static `INSECURE_BASE_URL` error.
+ *
+ * Rejected: a non-absolute URL, a scheme other than HTTP or HTTPS, embedded
+ * credentials, a query, a fragment, and plain HTTP to anything that is not
+ * loopback.
  */
-export declare function unrefTimer(handle: unknown): void;
+export declare function assertUsableBaseUrl(raw: string): URL;
+/** Validate the API key before any request is built. */
+export declare function assertApiKey(apiKey: string): string;
+/** Validate a caller- or SDK-generated idempotency key. */
+export declare function assertIdempotencyKey(key: string): string;
+/** Resolve and bound the per-call transport options. */
+export declare function resolveTransportOptions(options: {
+    timeoutMs?: number;
+    transportRetries?: number;
+}): {
+    timeoutMs: number;
+    transportRetries: number;
+};
+/** Keep a pending timer from holding the process open, when the runtime allows it. */
+export declare function unrefTimer(timer: unknown): void;
+/**
+ * A transport bound to one base URL and one bearer secret.
+ *
+ * The class owns the retry loop, so a retry always reuses the same idempotency
+ * key: the key is part of `TransportRequest` and is never regenerated.
+ */
+export declare class HttpTransport {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(config: TransportConfig);
+    /** The origin the transport will talk to; safe for tests and diagnostics. */
+    get endpointOrigin(): string;
+    /** Validate the body, then send it, retrying only transport-level failures. */
+    send(request: TransportRequest): Promise<unknown>;
+    private buildUrl;
+    private attempt;
+}
 //# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,0BAA0B,QAAkB,CAAC;AAC1D,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAI3C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAiH5B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAOhD"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,KAAK,EAAY,SAAS,EAAa,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF,sEAAsE;AACtE,eAAO,MAAM,MAAM;IACjB,sDAAsD;;IAEtD,iDAAiD;;IAEjD,oCAAoC;;IAEpC,8CAA8C;;IAE9C,wDAAwD;;IAExD,+DAA+D;;IAE/D,wDAAwD;;EAExD,CAAC;AAwBH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,aAAa,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiB5D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAuBpD;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKxD;AASD,wDAAwD;AACxD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAUlD;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAI/C;AA0GD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAEtC,YAAY,MAAM,EAAE,eAAe,EAIlC;IAED,6EAA6E;IAC7E,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,+EAA+E;IACzE,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CA4BtD;IAED,OAAO,CAAC,QAAQ;YAKF,OAAO;CA6CtB"}