@syndroo/sdk 0.4.0-rc.1

package/dist/client.js

@@ -0,0 +1,354 @@
+/**
+ * `SyndrooClient` — a thin, dependency-free client for the Syndroo HTTP API.
+ *
+ * The client wraps the documented `/v1` contract. It deliberately does not add
+ * server features: it creates, reads, lists, and waits, and it never invents a
+ * delivery result that the server did not report.
+ */
+import { SyndrooAbortError, SyndrooApiError, SyndrooConfigError, SyndrooError, SyndrooValidationError, SyndrooWaitTimeoutError, } from "./errors.js";
+import { DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, MIN_MAX_RESPONSE_BYTES, sendRequest, unrefTimer, } from "./http.js";
+import { isPostTerminal, parseHealth, parsePostDetail, parsePostList, parsePostReceipt, } from "./types.js";
+export const DEFAULT_WAIT_TIMEOUT_MS = 60_000;
+export const DEFAULT_POLL_INTERVAL_MS = 250;
+export const DEFAULT_MAX_POLL_INTERVAL_MS = 2_000;
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+ * Client for one Syndroo instance.
+ *
+ * ```ts
+ * const syndroo = new SyndrooClient({
+ *   baseUrl: process.env.SYNDROO_BASE_URL!,
+ *   apiKey: process.env.SYNDROO_API_KEY!,
+ * });
+ *
+ * const receipt = await syndroo.posts.create(
+ *   { content: "We just shipped a new release.", platforms: ["bluesky"] },
+ *   { idempotencyKey: "release-announcement-001" },
+ * );
+ *
+ * const post = await syndroo.posts.get(receipt.id);
+ * ```
+ */
+export class SyndrooClient {
+    posts;
+    #config;
+    #waitTimeoutMs;
+    constructor(options) {
+        this.#config = resolveConfig(options);
+        this.#waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+        validatePositiveDuration(this.#waitTimeoutMs, "waitTimeoutMs");
+        if (typeof globalThis.fetch !== "function") {
+            throw new SyndrooConfigError("This runtime has no global fetch(). The SDK requires Node.js 22 or newer.");
+        }
+        this.posts = new PostsResource(this.#config, this.#waitTimeoutMs);
+    }
+    /**
+     * `GET /health`. Syndroo's health endpoint is unauthenticated, so the client
+     * sends no Authorization header here. It proves reachability, not that the
+     * API key is correct or that the deployment can publish.
+     */
+    async health(options = {}) {
+        const response = await sendRequest(this.#config, {
+            method: "GET",
+            path: "/health",
+            authenticated: false,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        return parseHealth(response.body, { status: response.status });
+    }
+}
+/** The posts resource: create, read, list, and bounded status wait. */
+export class PostsResource {
+    #config;
+    #defaultWaitTimeoutMs;
+    constructor(config, defaultWaitTimeoutMs) {
+        this.#config = config;
+        this.#defaultWaitTimeoutMs = defaultWaitTimeoutMs;
+    }
+    /**
+     * `POST /v1/posts`. The returned receipt is an acceptance result: HTTP 202
+     * means the request is queued for processing, not that any platform
+     * published it. The SDK performs exactly one request and never retries it.
+     */
+    async create(input, options = {}) {
+        validateCreateInput(input);
+        const idempotencyKey = options.idempotencyKey === undefined
+            ? undefined
+            : validateIdempotencyKey(options.idempotencyKey);
+        const response = await sendRequest(this.#config, {
+            method: "POST",
+            path: "/v1/posts",
+            json: input,
+            idempotencyKey,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        return parsePostReceipt(response.body, {
+            status: response.status,
+            requestMayHaveBeenApplied: true,
+        });
+    }
+    /** `GET /v1/posts/<id>`. Read-only, so repeating it is safe. */
+    async get(id, options = {}) {
+        const postId = validatePostId(id);
+        const response = await sendRequest(this.#config, {
+            method: "GET",
+            path: `/v1/posts/${encodeURIComponent(postId)}`,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        return parsePostDetail(response.body, { status: response.status });
+    }
+    /** `GET /v1/posts`, newest first. */
+    async list(options = {}) {
+        const limit = options.limit === undefined ? undefined : validateLimit(options.limit);
+        const response = await sendRequest(this.#config, {
+            method: "GET",
+            path: "/v1/posts",
+            query: limit === undefined ? undefined : { limit: String(limit) },
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        return parsePostList(response.body, { status: response.status });
+    }
+    /**
+     * Reads the post until it reaches a terminal status (`published`, `partial`,
+     * or `failed`) or the wait budget runs out.
+     *
+     * Waiting is read-only: it never creates, cancels, or resends a post, so a
+     * timeout leaves the server-side work running and only stops this client from
+     * waiting. On timeout it throws `SyndrooWaitTimeoutError`, which keeps the
+     * post id, the last status, and the last transient error so a caller can
+     * resume instead of starting over.
+     */
+    async wait(id, options = {}) {
+        const postId = validatePostId(id);
+        const timeoutMs = options.timeoutMs ?? this.#defaultWaitTimeoutMs;
+        const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const maxPollIntervalMs = options.maxPollIntervalMs ?? DEFAULT_MAX_POLL_INTERVAL_MS;
+        validatePositiveDuration(timeoutMs, "timeoutMs");
+        validatePositiveDuration(pollIntervalMs, "pollIntervalMs");
+        validatePositiveDuration(maxPollIntervalMs, "maxPollIntervalMs");
+        const deadline = Date.now() + timeoutMs;
+        let interval = Math.min(pollIntervalMs, maxPollIntervalMs);
+        let lastPost;
+        let lastError;
+        for (;;) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                break;
+            }
+            try {
+                const post = await this.get(postId, {
+                    signal: options.signal,
+                    timeoutMs: Math.max(1, Math.min(remaining, this.#config.timeoutMs)),
+                });
+                lastPost = post;
+                lastError = undefined;
+                if (isPostTerminal(post.status)) {
+                    return post;
+                }
+            }
+            catch (error) {
+                const failure = toSyndrooError(error);
+                if (isFatalWaitFailure(failure)) {
+                    throw failure;
+                }
+                lastError = failure;
+                if (failure instanceof SyndrooApiError && failure.retryAfterMs !== undefined) {
+                    interval = Math.max(interval, failure.retryAfterMs);
+                }
+            }
+            const pause = Math.min(interval, Math.max(0, deadline - Date.now()));
+            if (pause > 0) {
+                await sleep(pause, options.signal);
+            }
+            interval = Math.min(interval * 2, maxPollIntervalMs);
+        }
+        throw new SyndrooWaitTimeoutError(waitTimeoutMessage(postId, timeoutMs, lastPost, lastError), {
+            postId,
+            timeoutMs,
+            lastStatus: lastPost?.status,
+            lastPost,
+            lastError,
+        });
+    }
+}
+function waitTimeoutMessage(postId, timeoutMs, lastPost, lastError) {
+    const observed = lastPost === undefined
+        ? "no status was observed"
+        : `the last observed status was "${lastPost.status}"`;
+    const failure = lastError === undefined ? "" : ` The last status read failed with: ${lastError.message}`;
+    return (`Stopped waiting for post ${postId} after ${timeoutMs}ms: ${observed}. ` +
+        "Waiting only reads, so no post was created or cancelled and the server-side " +
+        "work continues; resume with posts.get or a longer posts.wait." +
+        failure);
+}
+/**
+ * Only transient conditions keep a wait going. Authentication, validation, and
+ * "not found" are configuration or state problems that will not fix themselves
+ * by polling, so they surface immediately.
+ */
+function isFatalWaitFailure(error) {
+    if (error instanceof SyndrooAbortError ||
+        error instanceof SyndrooConfigError ||
+        error instanceof SyndrooValidationError) {
+        return true;
+    }
+    if (error instanceof SyndrooApiError) {
+        return error.status < 500 && error.status !== 429;
+    }
+    return false;
+}
+function toSyndrooError(error) {
+    if (error instanceof SyndrooError) {
+        return error;
+    }
+    return new SyndrooError(error instanceof Error ? error.message : "Unknown failure", { code: "UNKNOWN", cause: error });
+}
+function resolveConfig(options) {
+    const baseUrl = normalizeBaseUrl(options.baseUrl, options.allowInsecureHttp === true);
+    const apiKey = validateApiKey(options.apiKey);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    validatePositiveDuration(timeoutMs, "timeoutMs");
+    if (!Number.isInteger(maxResponseBytes) ||
+        maxResponseBytes < MIN_MAX_RESPONSE_BYTES) {
+        throw new SyndrooConfigError(`maxResponseBytes must be an integer of at least ${MIN_MAX_RESPONSE_BYTES} bytes.`);
+    }
+    return { baseUrl, apiKey, timeoutMs, maxResponseBytes };
+}
+function normalizeBaseUrl(value, allowInsecureHttp) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new SyndrooConfigError("baseUrl is required, for example https://syndroo.example.com.");
+    }
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        throw new SyndrooConfigError(`baseUrl must be an absolute URL, received "${value.trim()}".`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new SyndrooConfigError(`baseUrl must use http or https, received "${url.protocol}".`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new SyndrooConfigError("baseUrl must not embed credentials; pass the API key as apiKey so it is sent only as a Bearer header.");
+    }
+    if (url.search !== "" || url.hash !== "") {
+        throw new SyndrooConfigError("baseUrl must not include a query string or fragment.");
+    }
+    if (url.protocol === "http:" &&
+        !allowInsecureHttp &&
+        !isLoopbackHost(url.hostname)) {
+        throw new SyndrooConfigError("baseUrl must use https outside loopback: a bearer token sent over plaintext " +
+            "is readable on the path. Pass allowInsecureHttp: true only for a " +
+            "deliberate plaintext deployment.");
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+}
+function isLoopbackHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[/u, "").replace(/\]$/u, "");
+    return (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "::1" ||
+        host === "0:0:0:0:0:0:0:1" ||
+        host.startsWith("127."));
+}
+function validateApiKey(value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new SyndrooConfigError("apiKey is required. Keep it in a server, CLI, or CI credential store, " +
+            "never in client-side code or a NEXT_PUBLIC_* variable.");
+    }
+    if (/\s/u.test(value)) {
+        throw new SyndrooConfigError("apiKey must not contain whitespace or line breaks.");
+    }
+    return value;
+}
+function validatePositiveDuration(value, label) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new SyndrooConfigError(`${label} must be a positive, finite number of milliseconds.`);
+    }
+}
+function validateCreateInput(input) {
+    if (input === null || typeof input !== "object") {
+        throw new SyndrooValidationError("A post requires a content string and a list of platforms.");
+    }
+    if (typeof input.content !== "string" || input.content.trim().length === 0) {
+        throw new SyndrooValidationError("content must be a non-empty string.");
+    }
+    if (!Array.isArray(input.platforms) || input.platforms.length === 0) {
+        throw new SyndrooValidationError("platforms must be a non-empty array of platform names.");
+    }
+    input.platforms.forEach((platform, index) => {
+        if (typeof platform !== "string" || platform.trim().length === 0) {
+            throw new SyndrooValidationError(`platforms[${index}] must be a non-empty string.`);
+        }
+    });
+    if (input.scheduledAt !== undefined) {
+        if (typeof input.scheduledAt !== "string" ||
+            Number.isNaN(Date.parse(input.scheduledAt))) {
+            throw new SyndrooValidationError("scheduledAt must be an ISO 8601 date-time string with an explicit " +
+                "offset, for example 2030-01-02T03:04:05.000Z.");
+        }
+    }
+    const overrides = input.overrides;
+    if (overrides !== undefined) {
+        if (overrides === null || typeof overrides !== "object") {
+            throw new SyndrooValidationError("overrides must be an object keyed by platform name.");
+        }
+        for (const [platform, override] of Object.entries(overrides)) {
+            if (override === null || typeof override !== "object") {
+                throw new SyndrooValidationError(`overrides.${platform} must be an object with an optional content string.`);
+            }
+            const content = override.content;
+            if (content !== undefined && typeof content !== "string") {
+                throw new SyndrooValidationError(`overrides.${platform}.content must be a string.`);
+            }
+        }
+    }
+}
+function validateIdempotencyKey(value) {
+    if (typeof value !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(value)) {
+        throw new SyndrooValidationError("idempotencyKey must use 1-128 letters, digits, dots, underscores, colons, " +
+            "or hyphens, and must be reused for the same logical post.");
+    }
+    return value;
+}
+function validatePostId(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new SyndrooValidationError("A post id is required.");
+    }
+    return value;
+}
+function validateLimit(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 100) {
+        throw new SyndrooValidationError("limit must be an integer between 1 and 100.");
+    }
+    return value;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new SyndrooAbortError("Waiting was aborted before the next status read. Nothing was created or cancelled.", { cause: signal.reason }));
+            return;
+        }
+        const handle = setTimeout(() => {
+            finish();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            finish();
+            reject(new SyndrooAbortError("Waiting was aborted. Nothing was created or cancelled; the post continues on the server.", { cause: signal?.reason }));
+        };
+        function finish() {
+            clearTimeout(handle);
+            signal?.removeEventListener("abort", onAbort);
+        }
+        unrefTimer(handle);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,sBAAsB,EACtB,WAAW,EACX,UAAU,GAEX,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,EACb,gBAAgB,GAOjB,MAAM,YAAY,CAAC;AAEpB,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAC5C,MAAM,CAAC,MAAM,4BAA4B,GAAG,KAAK,CAAC;AAElD,MAAM,uBAAuB,GAAG,0BAA0B,CAAC;AAiD3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAa;IACf,KAAK,CAAgB;IACrB,OAAO,CAAkB;IACzB,cAAc,CAAS;IAEhC,YAAY,OAA6B;QACvC,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;QACvE,wBAAwB,CAAC,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;QAE/D,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YAC3C,MAAM,IAAI,kBAAkB,CAC1B,2EAA2E,CAC5E,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,OAAO,GAAmB,EAAE;QACvC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE;YAC/C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,SAAS;YACf,aAAa,EAAE,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,aAAa;IACf,OAAO,CAAkB;IACzB,qBAAqB,CAAS;IAEvC,YAAY,MAAuB,EAAE,oBAA4B;QAC/D,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,qBAAqB,GAAG,oBAAoB,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CACV,KAAsB,EACtB,OAAO,GAAsB,EAAE;QAE/B,mBAAmB,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,cAAc,GAClB,OAAO,CAAC,cAAc,KAAK,SAAS;YAClC,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,sBAAsB,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE;YAC/C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK;YACX,cAAc;YACd,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC,CAAC;QAEH,OAAO,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE;YACrC,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,yBAAyB,EAAE,IAAI;SAChC,CAAC,CAAC;IACL,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,GAAG,CAAC,EAAU,EAAE,OAAO,GAAmB,EAAE;QAChD,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE;YAC/C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,aAAa,kBAAkB,CAAC,MAAM,CAAC,EAAE;YAC/C,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC,CAAC;QAEH,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,IAAI,CAAC,OAAO,GAAqB,EAAE;QACvC,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE;YAC/C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE;YACjE,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CAAC,CAAC;QAEH,OAAO,aAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,IAAI,CAAC,EAAU,EAAE,OAAO,GAAgB,EAAE;QAC9C,MAAM,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,qBAAqB,CAAC;QAClE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;QAC1E,MAAM,iBAAiB,GACrB,OAAO,CAAC,iBAAiB,IAAI,4BAA4B,CAAC;QAE5D,wBAAwB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QACjD,wBAAwB,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;QAC3D,wBAAwB,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;QAEjE,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACxC,IAAI,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;QAC3D,IAAI,QAAgC,CAAC;QACrC,IAAI,SAAmC,CAAC;QAExC,SAAS,CAAC;YACR,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAExC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;gBACnB,MAAM;YACR,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE;oBAClC,MAAM,EAAE,OAAO,CAAC,MAAM;oBACtB,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;iBACpE,CAAC,CAAC;gBACH,QAAQ,GAAG,IAAI,CAAC;gBAChB,SAAS,GAAG,SAAS,CAAC;gBAEtB,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;oBAChC,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;gBAEtC,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;oBAChC,MAAM,OAAO,CAAC;gBAChB,CAAC;gBAED,SAAS,GAAG,OAAO,CAAC;gBAEpB,IAAI,OAAO,YAAY,eAAe,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC7E,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;gBACtD,CAAC;YACH,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAErE,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,MAAM,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;YAED,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,iBAAiB,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,IAAI,uBAAuB,CAAC,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE;YAC5F,MAAM;YACN,SAAS;YACT,UAAU,EAAE,QAAQ,EAAE,MAAM;YAC5B,QAAQ;YACR,SAAS;SACV,CAAC,CAAC;IACL,CAAC;CACF;AAED,SAAS,kBAAkB,CACzB,MAAc,EACd,SAAiB,EACjB,QAAgC,EAChC,SAAmC;IAEnC,MAAM,QAAQ,GACZ,QAAQ,KAAK,SAAS;QACpB,CAAC,CAAC,wBAAwB;QAC1B,CAAC,CAAC,iCAAiC,QAAQ,CAAC,MAAM,GAAG,CAAC;IAC1D,MAAM,OAAO,GACX,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,sCAAsC,SAAS,CAAC,OAAO,EAAE,CAAC;IAE3F,OAAO,CACL,4BAA4B,MAAM,UAAU,SAAS,OAAO,QAAQ,IAAI;QACxE,8EAA8E;QAC9E,+DAA+D;QAC/D,OAAO,CACR,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,KAAmB;IAC7C,IACE,KAAK,YAAY,iBAAiB;QAClC,KAAK,YAAY,kBAAkB;QACnC,KAAK,YAAY,sBAAsB,EACvC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,KAAK,GAAG,CAAC;IACpD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,YAAY,CACrB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,EAC1D,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAClC,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,OAA6B;IAClD,MAAM,OAAO,GAAG,gBAAgB,CAC9B,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,iBAAiB,KAAK,IAAI,CACnC,CAAC;IACF,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC1D,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IAEhF,wBAAwB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAEjD,IACE,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC;QACnC,gBAAgB,GAAG,sBAAsB,EACzC,CAAC;QACD,MAAM,IAAI,kBAAkB,CAC1B,mDAAmD,sBAAsB,SAAS,CACnF,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,iBAA0B;IACjE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,kBAAkB,CAC1B,+DAA+D,CAChE,CAAC;IACJ,CAAC;IAED,IAAI,GAAQ,CAAC;IAEb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kBAAkB,CAC1B,8CAA8C,KAAK,CAAC,IAAI,EAAE,IAAI,CAC/D,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,kBAAkB,CAC1B,6CAA6C,GAAG,CAAC,QAAQ,IAAI,CAC9D,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,kBAAkB,CAC1B,uGAAuG,CACxG,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,kBAAkB,CAC1B,sDAAsD,CACvD,CAAC;IACJ,CAAC;IAED,IACE,GAAG,CAAC,QAAQ,KAAK,OAAO;QACxB,CAAC,iBAAiB;QAClB,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,EAC7B,CAAC;QACD,MAAM,IAAI,kBAAkB,CAC1B,8EAA8E;YAC5E,mEAAmE;YACnE,kCAAkC,CACrC,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;AAChC,CAAC;AAED,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE5E,OAAO,CACL,IAAI,KAAK,WAAW;QACpB,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC3B,IAAI,KAAK,KAAK;QACd,IAAI,KAAK,iBAAiB;QAC1B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CACxB,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,kBAAkB,CAC1B,wEAAwE;YACtE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,kBAAkB,CAC1B,oDAAoD,CACrD,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAa,EAAE,KAAa;IAC5D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,kBAAkB,CAC1B,GAAG,KAAK,qDAAqD,CAC9D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAsB;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,IAAI,sBAAsB,CAC9B,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,sBAAsB,CAAC,qCAAqC,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,sBAAsB,CAC9B,wDAAwD,CACzD,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE;QAC1C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,sBAAsB,CAC9B,aAAa,KAAK,+BAA+B,CAClD,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,IACE,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;YACrC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAC3C,CAAC;YACD,MAAM,IAAI,sBAAsB,CAC9B,oEAAoE;gBAClE,+CAA+C,CAClD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAA6C,KAAK,CAAC,SAAS,CAAC;IAE5E,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;YACxD,MAAM,IAAI,sBAAsB,CAC9B,qDAAqD,CACtD,CAAC;QACJ,CAAC;QAED,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACtD,MAAM,IAAI,sBAAsB,CAC9B,aAAa,QAAQ,qDAAqD,CAC3E,CAAC;YACJ,CAAC;YAED,MAAM,OAAO,GAAY,QAAQ,CAAC,OAAO,CAAC;YAE1C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACzD,MAAM,IAAI,sBAAsB,CAC9B,aAAa,QAAQ,4BAA4B,CAClD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAa;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,sBAAsB,CAC9B,4EAA4E;YAC1E,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,sBAAsB,CAAC,wBAAwB,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QACzD,MAAM,IAAI,sBAAsB,CAAC,6CAA6C,CAAC,CAAC;IAClF,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAA+B;IACxD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,CACJ,IAAI,iBAAiB,CACnB,oFAAoF,EACpF,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CACzB,CACF,CAAC;YACF,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,MAAM,EAAE,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,MAAM,EAAE,CAAC;YACT,MAAM,CACJ,IAAI,iBAAiB,CACnB,0FAA0F,EAC1F,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAC1B,CACF,CAAC;QACJ,CAAC,CAAC;QAEF,SAAS,MAAM;YACb,YAAY,CAAC,MAAM,CAAC,CAAC;YACrB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;QAED,UAAU,CAAC,MAAM,CAAC,CAAC;QACnB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Typed error hierarchy for the public Syndroo SDK.
+ *
+ * Every failure the SDK raises is a `SyndrooError`, so callers can narrow on
+ * one base class and still classify the outcome precisely. The
+ * `requestMayHaveBeenApplied` flag is the state that decides whether a resend
+ * is safe: it is true whenever a write may already have reached Syndroo, which
+ * is exactly the case where retrying with a new idempotency key could create a
+ * second post.
+ */
+import type { PostDetail } from "./types.js";
+export type SyndrooErrorCode = "CONFIG" | "VALIDATION" | "ABORTED" | "TIMEOUT" | "NETWORK" | "INVALID_RESPONSE" | "WAIT_TIMEOUT" | (string & {});
+export interface SyndrooErrorInit {
+    cause?: unknown | undefined;
+    requestMayHaveBeenApplied?: boolean | undefined;
+}
+export declare class SyndrooError<Code extends SyndrooErrorCode = SyndrooErrorCode> extends Error {
+    readonly code: Code;
+    readonly requestMayHaveBeenApplied: boolean;
+    constructor(message: string, init: SyndrooErrorInit & {
+        code: Code;
+    });
+}
+/** The client configuration itself is unusable, so no request was sent. */
+export declare class SyndrooConfigError extends SyndrooError<"CONFIG"> {
+    constructor(message: string);
+}
+/** The caller's argument cannot become a valid Syndroo request. */
+export declare class SyndrooValidationError extends SyndrooError<"VALIDATION"> {
+    constructor(message: string);
+}
+/** The caller aborted through an AbortSignal. */
+export declare class SyndrooAbortError extends SyndrooError<"ABORTED"> {
+    constructor(message: string, init?: SyndrooErrorInit);
+}
+/** The configured deadline elapsed before the response was received. */
+export declare class SyndrooTimeoutError extends SyndrooError<"TIMEOUT"> {
+    readonly timeoutMs: number;
+    constructor(message: string, init: SyndrooErrorInit & {
+        timeoutMs: number;
+    });
+}
+/**
+ * The request never produced an HTTP response. `networkCode` carries the
+ * runtime's error code, such as `ECONNREFUSED`, when one is available.
+ */
+export declare class SyndrooNetworkError extends SyndrooError<"NETWORK"> {
+    readonly networkCode?: string;
+    constructor(message: string, init: SyndrooErrorInit & {
+        networkCode?: string | undefined;
+    });
+}
+/**
+ * Syndroo answered, but the answer is not the documented JSON contract: a
+ * non-JSON body, a missing required field, or a body above the configured
+ * size limit. The outcome of a write is never inferred from a bad response.
+ */
+export declare class SyndrooResponseError extends SyndrooError<"INVALID_RESPONSE"> {
+    readonly status?: number;
+    readonly preview?: string;
+    constructor(message: string, init?: SyndrooErrorInit & {
+        status?: number | undefined;
+        preview?: string | undefined;
+    });
+}
+/**
+ * Syndroo rejected the request with a documented error envelope. `code` is the
+ * server's code such as `UNAUTHORIZED`, `POST_NOT_FOUND`,
+ * `IDEMPOTENCY_CONFLICT`, or `PLATFORM_NOT_CONFIGURED`, and `HTTP_<status>`
+ * when the body did not carry one.
+ */
+export declare class SyndrooApiError extends SyndrooError {
+    readonly status: number;
+    readonly retryAfterMs?: number;
+    constructor(message: string, init: SyndrooErrorInit & {
+        code: SyndrooErrorCode;
+        status: number;
+        retryAfterMs?: number | undefined;
+    });
+    /** Syndroo or an intermediary asked the client to slow down. */
+    get retryable(): boolean;
+}
+/** `posts.wait` reached its deadline before the post became terminal. */
+export declare class SyndrooWaitTimeoutError extends SyndrooError<"WAIT_TIMEOUT"> {
+    readonly postId: string;
+    readonly timeoutMs: number;
+    readonly lastStatus?: string;
+    readonly lastPost?: PostDetail;
+    readonly lastError?: SyndrooError;
+    constructor(message: string, init: {
+        postId: string;
+        timeoutMs: number;
+        lastStatus?: string | undefined;
+        lastPost?: PostDetail | undefined;
+        lastError?: SyndrooError | undefined;
+    });
+}
+export declare function isSyndrooError(value: unknown): value is SyndrooError;
+/**
+ * Internal helper for bounded diagnostics. Error messages and response
+ * previews must never grow with the size of an untrusted body.
+ */
+export declare function truncate(value: string, limit: number): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,162 @@
+/**
+ * Typed error hierarchy for the public Syndroo SDK.
+ *
+ * Every failure the SDK raises is a `SyndrooError`, so callers can narrow on
+ * one base class and still classify the outcome precisely. The
+ * `requestMayHaveBeenApplied` flag is the state that decides whether a resend
+ * is safe: it is true whenever a write may already have reached Syndroo, which
+ * is exactly the case where retrying with a new idempotency key could create a
+ * second post.
+ */
+export class SyndrooError extends Error {
+    code;
+    requestMayHaveBeenApplied;
+    constructor(message, init) {
+        super(message, { cause: init.cause });
+        this.name = "SyndrooError";
+        this.code = init.code;
+        this.requestMayHaveBeenApplied = init.requestMayHaveBeenApplied ?? false;
+    }
+}
+/** The client configuration itself is unusable, so no request was sent. */
+export class SyndrooConfigError extends SyndrooError {
+    constructor(message) {
+        super(message, { code: "CONFIG" });
+        this.name = "SyndrooConfigError";
+    }
+}
+/** The caller's argument cannot become a valid Syndroo request. */
+export class SyndrooValidationError extends SyndrooError {
+    constructor(message) {
+        super(message, { code: "VALIDATION" });
+        this.name = "SyndrooValidationError";
+    }
+}
+/** The caller aborted through an AbortSignal. */
+export class SyndrooAbortError extends SyndrooError {
+    constructor(message, init = {}) {
+        super(message, {
+            code: "ABORTED",
+            cause: init.cause,
+            requestMayHaveBeenApplied: init.requestMayHaveBeenApplied,
+        });
+        this.name = "SyndrooAbortError";
+    }
+}
+/** The configured deadline elapsed before the response was received. */
+export class SyndrooTimeoutError extends SyndrooError {
+    timeoutMs;
+    constructor(message, init) {
+        super(message, {
+            code: "TIMEOUT",
+            cause: init.cause,
+            requestMayHaveBeenApplied: init.requestMayHaveBeenApplied,
+        });
+        this.name = "SyndrooTimeoutError";
+        this.timeoutMs = init.timeoutMs;
+    }
+}
+/**
+ * The request never produced an HTTP response. `networkCode` carries the
+ * runtime's error code, such as `ECONNREFUSED`, when one is available.
+ */
+export class SyndrooNetworkError extends SyndrooError {
+    networkCode;
+    constructor(message, init) {
+        super(message, {
+            code: "NETWORK",
+            cause: init.cause,
+            requestMayHaveBeenApplied: init.requestMayHaveBeenApplied,
+        });
+        this.name = "SyndrooNetworkError";
+        if (init.networkCode !== undefined) {
+            this.networkCode = init.networkCode;
+        }
+    }
+}
+/**
+ * Syndroo answered, but the answer is not the documented JSON contract: a
+ * non-JSON body, a missing required field, or a body above the configured
+ * size limit. The outcome of a write is never inferred from a bad response.
+ */
+export class SyndrooResponseError extends SyndrooError {
+    status;
+    preview;
+    constructor(message, init = {}) {
+        super(message, {
+            code: "INVALID_RESPONSE",
+            cause: init.cause,
+            requestMayHaveBeenApplied: init.requestMayHaveBeenApplied,
+        });
+        this.name = "SyndrooResponseError";
+        if (init.status !== undefined) {
+            this.status = init.status;
+        }
+        if (init.preview !== undefined) {
+            this.preview = init.preview;
+        }
+    }
+}
+/**
+ * Syndroo rejected the request with a documented error envelope. `code` is the
+ * server's code such as `UNAUTHORIZED`, `POST_NOT_FOUND`,
+ * `IDEMPOTENCY_CONFLICT`, or `PLATFORM_NOT_CONFIGURED`, and `HTTP_<status>`
+ * when the body did not carry one.
+ */
+export class SyndrooApiError extends SyndrooError {
+    status;
+    retryAfterMs;
+    constructor(message, init) {
+        super(message, {
+            code: init.code,
+            cause: init.cause,
+            requestMayHaveBeenApplied: init.requestMayHaveBeenApplied,
+        });
+        this.name = "SyndrooApiError";
+        this.status = init.status;
+        if (init.retryAfterMs !== undefined) {
+            this.retryAfterMs = init.retryAfterMs;
+        }
+    }
+    /** Syndroo or an intermediary asked the client to slow down. */
+    get retryable() {
+        return this.status === 429 || this.status >= 500;
+    }
+}
+/** `posts.wait` reached its deadline before the post became terminal. */
+export class SyndrooWaitTimeoutError extends SyndrooError {
+    postId;
+    timeoutMs;
+    lastStatus;
+    lastPost;
+    lastError;
+    constructor(message, init) {
+        super(message, { code: "WAIT_TIMEOUT", requestMayHaveBeenApplied: false });
+        this.name = "SyndrooWaitTimeoutError";
+        this.postId = init.postId;
+        this.timeoutMs = init.timeoutMs;
+        if (init.lastStatus !== undefined) {
+            this.lastStatus = init.lastStatus;
+        }
+        if (init.lastPost !== undefined) {
+            this.lastPost = init.lastPost;
+        }
+        if (init.lastError !== undefined) {
+            this.lastError = init.lastError;
+        }
+    }
+}
+export function isSyndrooError(value) {
+    return value instanceof SyndrooError;
+}
+/**
+ * Internal helper for bounded diagnostics. Error messages and response
+ * previews must never grow with the size of an untrusted body.
+ */
+export function truncate(value, limit) {
+    if (value.length <= limit) {
+        return value;
+    }
+    return `${value.slice(0, limit)}...[${value.length - limit} more characters]`;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH,MAAM,OAAO,YAEX,SAAQ,KAAK;IACJ,IAAI,CAAO;IACX,yBAAyB,CAAU;IAE5C,YACE,OAAe,EACf,IAAuC;QAEvC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,yBAAyB,GAAG,IAAI,CAAC,yBAAyB,IAAI,KAAK,CAAC;IAC3E,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,kBAAmB,SAAQ,YAAsB;IAC5D,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,OAAO,sBAAuB,SAAQ,YAA0B;IACpE,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,iDAAiD;AACjD,MAAM,OAAO,iBAAkB,SAAQ,YAAuB;IAC5D,YAAY,OAAe,EAAE,IAAI,GAAqB,EAAE;QACtD,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,yBAAyB,EAAE,IAAI,CAAC,yBAAyB;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,mBAAoB,SAAQ,YAAuB;IACrD,SAAS,CAAS;IAE3B,YACE,OAAe,EACf,IAA8C;QAE9C,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,yBAAyB,EAAE,IAAI,CAAC,yBAAyB;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,YAAuB;IACrD,WAAW,CAAU;IAE9B,YACE,OAAe,EACf,IAA6D;QAE7D,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,yBAAyB,EAAE,IAAI,CAAC,yBAAyB;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAElC,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACtC,CAAC;IACH,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,YAAgC;IAC/D,MAAM,CAAU;IAChB,OAAO,CAAU;IAE1B,YACE,OAAe,EACf,IAAI,GAGA,EAAE;QAEN,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,kBAAkB;YACxB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,yBAAyB,EAAE,IAAI,CAAC,yBAAyB;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC9B,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY;IACtC,MAAM,CAAS;IACf,YAAY,CAAU;IAE/B,YACE,OAAe,EACf,IAIC;QAED,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,yBAAyB,EAAE,IAAI,CAAC,yBAAyB;SAC1D,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAE1B,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACxC,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;IACnD,CAAC;CACF;AAED,yEAAyE;AACzE,MAAM,OAAO,uBAAwB,SAAQ,YAA4B;IAC9D,MAAM,CAAS;IACf,SAAS,CAAS;IAClB,UAAU,CAAU;IACpB,QAAQ,CAAc;IACtB,SAAS,CAAgB;IAElC,YACE,OAAe,EACf,IAMC;QAED,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,yBAAyB,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAEhC,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YAClC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACpC,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAChC,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAClC,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,KAAK,YAAY,YAAY,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa,EAAE,KAAa;IACnD,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK,mBAAmB,CAAC;AAChF,CAAC"}