@bastamp/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aletheia Tech Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# @bastamp/sdk
+
+Official TypeScript SDK for the [BA | Stamp](https://bastamp.com) REST API. Anchor SHA-256 hashes of arbitrary files on the Polygon blockchain (and Bitcoin via OpenTimestamps) from any Node.js, Bun, Deno, or browser runtime.
+
+The bytes of the file you're stamping never leave your machine — only the SHA-256 hash is sent.
+
+```ts
+import { BAStamp, hashFile } from "@bastamp/sdk";
+import { readFile } from "node:fs/promises";
+
+const client = new BAStamp({ apiKey: process.env.BASTAMP_API_KEY! });
+
+const bytes = await readFile("contract.pdf");
+const { stamp, creditsCharged } = await client.stamps.create({
+  contentHash: await hashFile(bytes),
+  fileName: "contract.pdf",
+  fileSize: bytes.length,
+  mimeType: "application/pdf",
+});
+
+console.log(stamp.contentHash, creditsCharged);
+```
+
+## Install
+
+```bash
+npm install @bastamp/sdk
+# or
+pnpm add @bastamp/sdk
+# or
+yarn add @bastamp/sdk
+```
+
+Requires Node 20+ (uses `fetch`, `crypto.subtle`, and `crypto.randomUUID` from the platform). Works in modern browsers and Bun/Deno without changes.
+
+## Auth
+
+Create an API key at [bastamp.com/account/api-keys](https://bastamp.com/account/api-keys). The plain value is shown once — store it in a secret manager (Vercel/GitHub Actions/1Password). Format: `ba_live_<32 hex chars>`.
+
+## Usage
+
+### Create a stamp
+
+```ts
+const { stamp, creditsCharged } = await client.stamps.create({
+  contentHash: "0x...",
+  fileName: "contract.pdf",   // optional, metadata only
+  fileSize: 184326,           // optional, bytes
+  mimeType: "application/pdf",// optional
+  jurisdiction: "IT",         // optional, drives certificate's legal framing
+  locale: "it",               // optional, certificate language
+});
+// stamp.duplicate === true if this account already owned the hash → 0 credits charged
+```
+
+The SDK auto-generates an `Idempotency-Key` per call. To override (e.g. tie idempotency to a workflow run id):
+
+```ts
+await client.stamps.create({ contentHash }, { idempotencyKey: `gh-run-${runId}` });
+```
+
+### Batch up to 100 stamps in one call
+
+```ts
+const { results, creditsCharged, duplicateCount } = await client.stamps.createBatch({
+  items: [
+    { contentHash: "0x...", fileName: "a.pdf" },
+    { contentHash: "0x...", fileName: "b.pdf" },
+  ],
+  jurisdiction: "IT",
+  locale: "it",
+});
+```
+
+### Look up a stamp
+
+```ts
+const s = await client.stamps.get("0x...");
+// s.status: "pending" | "anchored"
+// s.anchor: { chain, merkleRoot, txHash, blockNumber, blockTime, bitcoin } | null
+```
+
+### Download the certificate PDF
+
+```ts
+const pdf = await client.stamps.downloadCertificate("0x...", { locale: "it", jurisdiction: "IT" });
+// pdf is a Uint8Array — write to disk:
+await fs.writeFile("certificate.pdf", pdf);
+```
+
+Throws `BAStampConflictError` (`type === "not_anchored"`) if the stamp is still pending. Anchoring lands at the next 5-minute batch tick.
+
+### Account info
+
+```ts
+const account = await client.account.get();
+console.log(account.credits);
+```
+
+### Hash any byte source
+
+```ts
+import { hashFile } from "@bastamp/sdk";
+
+await hashFile(uint8Array);   // 0x...
+await hashFile(arrayBuffer);  // 0x...
+await hashFile(blob);         // 0x... (browser File / Blob)
+await hashFile(buffer);       // 0x... (Node Buffer)
+```
+
+All variants delegate to `crypto.subtle.digest("SHA-256", ...)` — the computation is local; no network call.
+
+## Errors
+
+```ts
+import {
+  BAStampNoCreditsError,
+  BAStampUnauthorizedError,
+  BAStampConflictError,
+} from "@bastamp/sdk";
+
+try {
+  await client.stamps.create({ contentHash });
+} catch (err) {
+  if (err instanceof BAStampNoCreditsError) {
+    // 402 — top up at bastamp.com/#pricing
+  } else if (err instanceof BAStampUnauthorizedError) {
+    // 401 — rotate the key
+  } else if (err instanceof BAStampConflictError && err.type === "idempotency_conflict") {
+    // 409 — Idempotency-Key reused with a different payload
+  } else {
+    throw err;
+  }
+}
+```
+
+Error class hierarchy:
+
+| Status | Class | When |
+|---|---|---|
+| 400 | `BAStampInvalidRequestError` | Bad hash format, missing field, etc. |
+| 401 | `BAStampUnauthorizedError` | Missing / wrong Bearer token |
+| 402 | `BAStampNoCreditsError` | Account is out of credits |
+| 404 | `BAStampNotFoundError` | Stamp doesn't exist |
+| 409 | `BAStampConflictError` | Idempotency conflict, or certificate requested before anchor |
+| 429 | `BAStampRateLimitedError` | Rate limited (SDK retries automatically; surfaced only if retries exhaust) |
+| other | `BAStampError` | Base class — `.status`, `.type`, `.body` |
+
+## Retries
+
+The SDK retries on 408, 429, 502, 503, 504 and on network errors. Up to `maxRetries` attempts (default 3, configurable via `new BAStamp({ apiKey, maxRetries })`) with exponential backoff + jitter (~200 ms → 5 s capped). Honors `Retry-After` headers when present.
+
+Non-retryable: 400, 401, 402, 404, 409. They fail immediately.
+
+## Cancel a request
+
+```ts
+const ctrl = new AbortController();
+setTimeout(() => ctrl.abort(), 5_000);
+await client.stamps.create({ contentHash }, { signal: ctrl.signal });
+```
+
+## Examples
+
+See [examples/basic.ts](./examples/basic.ts) for a runnable end-to-end script (`tsx examples/basic.ts <file>`).
+
+## Why an official SDK
+
+The REST API is straightforward — anyone can call it with `fetch`. The SDK exists because:
+
+- Type-safe request bodies and responses from the [OpenAPI spec](https://bastamp.com/openapi.yaml).
+- Sensible defaults: retries, idempotency keys, error subclasses.
+- One-line file hashing via `hashFile` that works across Node, browser, Bun, Deno.
+- No dependencies — fewer supply-chain things to worry about.
+
+For verifying stamps independently (without trusting bastamp.com), see the [open-source verifier](https://github.com/stamp-verify/stamp-verify).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/client.d.ts

@@ -0,0 +1,66 @@
+import type { Account, CertificateOptions, ClientOptions, CreateBatchResponse, CreateStampResponse, RequestOptions, Stamp, StampInput, BatchInput } from "./types.js";
+/**
+ * BA | Stamp REST client.
+ *
+ * ```ts
+ * import { BAStamp, hashFile } from "@bastamp/sdk";
+ * const client = new BAStamp({ apiKey: process.env.BASTAMP_API_KEY! });
+ *
+ * const bytes = await fs.readFile("contract.pdf");
+ * const { stamp } = await client.stamps.create({
+ *   contentHash: await hashFile(bytes),
+ *   fileName: "contract.pdf",
+ *   fileSize: bytes.length,
+ *   mimeType: "application/pdf",
+ * });
+ * console.log("anchored hash:", stamp.contentHash);
+ * ```
+ */
+export declare class BAStamp {
+    #private;
+    readonly stamps: StampsResource;
+    readonly account: AccountResource;
+    constructor(opts: ClientOptions);
+    /** @internal */
+    _request<T>(method: "GET" | "POST", path: string, options?: {
+        body?: unknown;
+        query?: Record<string, string | undefined>;
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+        raw?: boolean;
+    }): Promise<T>;
+}
+declare class StampsResource {
+    #private;
+    constructor(client: BAStamp);
+    /**
+     * Anchor a single SHA-256 hash. Charges 1 credit; returns
+     * `{ duplicate: true, ...}` with 0 charge if the caller already owns
+     * this exact hash.
+     */
+    create(input: StampInput, options?: RequestOptions): Promise<CreateStampResponse>;
+    /**
+     * Anchor up to 100 hashes in one call. One credit per *new* item;
+     * duplicates aren't charged but still appear in `results`.
+     */
+    createBatch(input: BatchInput, options?: RequestOptions): Promise<CreateBatchResponse>;
+    /**
+     * Read a stamp's current status and on-chain anchor data. Returns
+     * `status: "pending"` until the next batch tick (~5 minutes) anchors
+     * it on Polygon.
+     */
+    get(contentHash: string, options?: RequestOptions): Promise<Stamp>;
+    /**
+     * Download the PDF certificate for a stamp as raw bytes. Throws 409
+     * `not_anchored` if the stamp hasn't anchored on Polygon yet.
+     */
+    downloadCertificate(contentHash: string, certOptions?: CertificateOptions & RequestOptions): Promise<Uint8Array>;
+}
+declare class AccountResource {
+    #private;
+    constructor(client: BAStamp);
+    /** Get the authenticated account's id, email, and remaining credits. */
+    get(options?: RequestOptions): Promise<Account>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,OAAO,EAEP,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,KAAK,EACL,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBAMtB,IAAI,EAAE,aAAa;IAY/B,gBAAgB;IACV,QAAQ,CAAC,CAAC,EACd,MAAM,EAAE,KAAK,GAAG,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;QAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,WAAW,CAAC;QAErB,GAAG,CAAC,EAAE,OAAO,CAAC;KACV,GACL,OAAO,CAAC,CAAC,CAAC;CA6Dd;AAED,cAAM,cAAc;;gBAEN,MAAM,EAAE,OAAO;IAI3B;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQ3F;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAchG;;;;OAIG;IACG,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,KAAK,CAAC;IAM5E;;;OAGG;IACG,mBAAmB,CACvB,WAAW,EAAE,MAAM,EACnB,WAAW,GAAE,kBAAkB,GAAG,cAAmB,GACpD,OAAO,CAAC,UAAU,CAAC;CAavB;AAED,cAAM,eAAe;;gBAEP,MAAM,EAAE,OAAO;IAI3B,wEAAwE;IAClE,GAAG,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;CAG1D"}

package/dist/client.js

@@ -0,0 +1,197 @@
+import { BAStampError, BAStampInvalidRequestError, BAStampUnauthorizedError, BAStampNoCreditsError, BAStampNotFoundError, BAStampConflictError, BAStampRateLimitedError, } from "./errors.js";
+import { backoffMs, retryAfterMs, shouldRetry, sleep } from "./retry.js";
+const DEFAULT_BASE_URL = "https://bastamp.com";
+const DEFAULT_MAX_RETRIES = 3;
+const USER_AGENT = "bastamp-sdk-ts/0.1.0";
+/**
+ * BA | Stamp REST client.
+ *
+ * ```ts
+ * import { BAStamp, hashFile } from "@bastamp/sdk";
+ * const client = new BAStamp({ apiKey: process.env.BASTAMP_API_KEY! });
+ *
+ * const bytes = await fs.readFile("contract.pdf");
+ * const { stamp } = await client.stamps.create({
+ *   contentHash: await hashFile(bytes),
+ *   fileName: "contract.pdf",
+ *   fileSize: bytes.length,
+ *   mimeType: "application/pdf",
+ * });
+ * console.log("anchored hash:", stamp.contentHash);
+ * ```
+ */
+export class BAStamp {
+    stamps;
+    account;
+    #apiKey;
+    #baseUrl;
+    #maxRetries;
+    #fetch;
+    constructor(opts) {
+        if (!opts?.apiKey || typeof opts.apiKey !== "string") {
+            throw new TypeError("BAStamp: `apiKey` is required");
+        }
+        this.#apiKey = opts.apiKey;
+        this.#baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.#maxRetries = Math.max(0, opts.maxRetries ?? DEFAULT_MAX_RETRIES);
+        this.#fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.stamps = new StampsResource(this);
+        this.account = new AccountResource(this);
+    }
+    /** @internal */
+    async _request(method, path, options = {}) {
+        const url = new URL(this.#baseUrl + path);
+        if (options.query) {
+            for (const [k, v] of Object.entries(options.query)) {
+                if (v != null)
+                    url.searchParams.set(k, v);
+            }
+        }
+        const headers = {
+            "Authorization": `Bearer ${this.#apiKey}`,
+            "User-Agent": USER_AGENT,
+            "Accept": options.raw ? "application/pdf, application/json" : "application/json",
+        };
+        let bodyString;
+        if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            bodyString = JSON.stringify(options.body);
+        }
+        if (options.idempotencyKey) {
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        }
+        let attempt = 0;
+        // The +1 reads naturally: maxRetries=3 means up to 4 attempts total.
+        while (true) {
+            let response;
+            try {
+                response = await this.#fetch(url.toString(), {
+                    method,
+                    headers,
+                    body: bodyString,
+                    signal: options.signal,
+                });
+            }
+            catch (err) {
+                // Network-level error (DNS, TCP, abort). Retry transient kinds.
+                if (attempt < this.#maxRetries && !(err instanceof DOMException && err.name === "AbortError")) {
+                    await sleep(backoffMs(attempt), options.signal);
+                    attempt++;
+                    continue;
+                }
+                throw err;
+            }
+            if (response.ok) {
+                if (options.raw)
+                    return response;
+                // 204 has no body
+                if (response.status === 204)
+                    return undefined;
+                return (await response.json());
+            }
+            const shouldRetryThis = shouldRetry(response.status) && attempt < this.#maxRetries;
+            if (shouldRetryThis) {
+                const waitMs = retryAfterMs(response.headers.get("retry-after")) ?? backoffMs(attempt);
+                await sleep(waitMs, options.signal);
+                attempt++;
+                continue;
+            }
+            throw await buildError(response);
+        }
+    }
+}
+class StampsResource {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * Anchor a single SHA-256 hash. Charges 1 credit; returns
+     * `{ duplicate: true, ...}` with 0 charge if the caller already owns
+     * this exact hash.
+     */
+    async create(input, options = {}) {
+        return this.#client._request("POST", "/api/v1/stamps", {
+            body: input,
+            idempotencyKey: options.idempotencyKey ?? randomIdempotencyKey(),
+            signal: options.signal,
+        });
+    }
+    /**
+     * Anchor up to 100 hashes in one call. One credit per *new* item;
+     * duplicates aren't charged but still appear in `results`.
+     */
+    async createBatch(input, options = {}) {
+        if (!Array.isArray(input.items) || input.items.length === 0) {
+            throw new TypeError("createBatch: `items` must be a non-empty array");
+        }
+        if (input.items.length > 100) {
+            throw new TypeError(`createBatch: max 100 items per call (got ${input.items.length})`);
+        }
+        return this.#client._request("POST", "/api/v1/stamps/batch", {
+            body: input,
+            idempotencyKey: options.idempotencyKey ?? randomIdempotencyKey(),
+            signal: options.signal,
+        });
+    }
+    /**
+     * Read a stamp's current status and on-chain anchor data. Returns
+     * `status: "pending"` until the next batch tick (~5 minutes) anchors
+     * it on Polygon.
+     */
+    async get(contentHash, options = {}) {
+        return this.#client._request("GET", `/api/v1/stamps/${encodeURIComponent(contentHash)}`, {
+            signal: options.signal,
+        });
+    }
+    /**
+     * Download the PDF certificate for a stamp as raw bytes. Throws 409
+     * `not_anchored` if the stamp hasn't anchored on Polygon yet.
+     */
+    async downloadCertificate(contentHash, certOptions = {}) {
+        const response = await this.#client._request("GET", `/api/v1/stamps/${encodeURIComponent(contentHash)}/certificate`, {
+            query: { locale: certOptions.locale, jurisdiction: certOptions.jurisdiction },
+            signal: certOptions.signal,
+            raw: true,
+        });
+        const buf = await response.arrayBuffer();
+        return new Uint8Array(buf);
+    }
+}
+class AccountResource {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** Get the authenticated account's id, email, and remaining credits. */
+    async get(options = {}) {
+        return this.#client._request("GET", "/api/v1/account", { signal: options.signal });
+    }
+}
+// ── helpers ──
+async function buildError(response) {
+    const text = await response.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch { /* not JSON */ }
+    const type = parsed?.error?.type ?? "unknown";
+    const message = parsed?.error?.message ?? text ?? `HTTP ${response.status}`;
+    const body = parsed ?? text;
+    switch (response.status) {
+        case 400: return new BAStampInvalidRequestError(message, body);
+        case 401: return new BAStampUnauthorizedError(message, body);
+        case 402: return new BAStampNoCreditsError(message, body);
+        case 404: return new BAStampNotFoundError(message, body);
+        case 409: return new BAStampConflictError(message, type, body);
+        case 429: return new BAStampRateLimitedError(message, body);
+        default:
+            return new BAStampError(message, response.status, type, body);
+    }
+}
+function randomIdempotencyKey() {
+    // crypto.randomUUID is available on Node 20+, all modern browsers, Bun, Deno.
+    return globalThis.crypto.randomUUID();
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Base error for any non-2xx response from the BA Stamp API. Subclasses
+ * narrow on the response code (401 → Unauthorized, 402 → NoCredits, etc.).
+ */
+export declare class BAStampError extends Error {
+    /** HTTP status code. */
+    readonly status: number;
+    /** Machine-readable code from the API's error envelope (snake_case). */
+    readonly type: string;
+    /** Raw response body (parsed when JSON, otherwise the string). */
+    readonly body: unknown;
+    constructor(message: string, status: number, type: string, body: unknown);
+}
+/** 400 — payload, hash, or parameter failed validation. */
+export declare class BAStampInvalidRequestError extends BAStampError {
+    constructor(message: string, body: unknown);
+}
+/** 401 — missing or wrong Authorization header. */
+export declare class BAStampUnauthorizedError extends BAStampError {
+    constructor(message: string, body: unknown);
+}
+/** 402 — account credits don't cover the request. Top up at bastamp.com/#pricing. */
+export declare class BAStampNoCreditsError extends BAStampError {
+    constructor(message: string, body: unknown);
+}
+/** 404 — no stamp exists for the requested hash. */
+export declare class BAStampNotFoundError extends BAStampError {
+    constructor(message: string, body: unknown);
+}
+/** 409 — Idempotency-Key reused with a different payload, or stamp not anchored yet for certificate. */
+export declare class BAStampConflictError extends BAStampError {
+    constructor(message: string, type: string, body: unknown);
+}
+/** 429 — rate-limited. SDK retries automatically; surfaced only if retries exhaust. */
+export declare class BAStampRateLimitedError extends BAStampError {
+    constructor(message: string, body: unknown);
+}
+//# 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":"AAAA;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAOzE;AAED,2DAA2D;AAC3D,qBAAa,0BAA2B,SAAQ,YAAY;gBAC9C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAI3C;AAED,mDAAmD;AACnD,qBAAa,wBAAyB,SAAQ,YAAY;gBAC5C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAI3C;AAED,qFAAqF;AACrF,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAI3C;AAED,oDAAoD;AACpD,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAI3C;AAED,wGAAwG;AACxG,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAIzD;AAED,uFAAuF;AACvF,qBAAa,uBAAwB,SAAQ,YAAY;gBAC3C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAI3C"}

package/dist/errors.js

@@ -0,0 +1,62 @@
+/**
+ * Base error for any non-2xx response from the BA Stamp API. Subclasses
+ * narrow on the response code (401 → Unauthorized, 402 → NoCredits, etc.).
+ */
+export class BAStampError extends Error {
+    /** HTTP status code. */
+    status;
+    /** Machine-readable code from the API's error envelope (snake_case). */
+    type;
+    /** Raw response body (parsed when JSON, otherwise the string). */
+    body;
+    constructor(message, status, type, body) {
+        super(message);
+        this.name = "BAStampError";
+        this.status = status;
+        this.type = type;
+        this.body = body;
+    }
+}
+/** 400 — payload, hash, or parameter failed validation. */
+export class BAStampInvalidRequestError extends BAStampError {
+    constructor(message, body) {
+        super(message, 400, "invalid_request", body);
+        this.name = "BAStampInvalidRequestError";
+    }
+}
+/** 401 — missing or wrong Authorization header. */
+export class BAStampUnauthorizedError extends BAStampError {
+    constructor(message, body) {
+        super(message, 401, "unauthorized", body);
+        this.name = "BAStampUnauthorizedError";
+    }
+}
+/** 402 — account credits don't cover the request. Top up at bastamp.com/#pricing. */
+export class BAStampNoCreditsError extends BAStampError {
+    constructor(message, body) {
+        super(message, 402, "no_credits", body);
+        this.name = "BAStampNoCreditsError";
+    }
+}
+/** 404 — no stamp exists for the requested hash. */
+export class BAStampNotFoundError extends BAStampError {
+    constructor(message, body) {
+        super(message, 404, "not_found", body);
+        this.name = "BAStampNotFoundError";
+    }
+}
+/** 409 — Idempotency-Key reused with a different payload, or stamp not anchored yet for certificate. */
+export class BAStampConflictError extends BAStampError {
+    constructor(message, type, body) {
+        super(message, 409, type, body);
+        this.name = "BAStampConflictError";
+    }
+}
+/** 429 — rate-limited. SDK retries automatically; surfaced only if retries exhaust. */
+export class BAStampRateLimitedError extends BAStampError {
+    constructor(message, body) {
+        super(message, 429, "rate_limited", body);
+        this.name = "BAStampRateLimitedError";
+    }
+}
+//# 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;;;GAGG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,wBAAwB;IACf,MAAM,CAAS;IACxB,wEAAwE;IAC/D,IAAI,CAAS;IACtB,kEAAkE;IACzD,IAAI,CAAU;IAEvB,YAAY,OAAe,EAAE,MAAc,EAAE,IAAY,EAAE,IAAa;QACtE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,2DAA2D;AAC3D,MAAM,OAAO,0BAA2B,SAAQ,YAAY;IAC1D,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAED,mDAAmD;AACnD,MAAM,OAAO,wBAAyB,SAAQ,YAAY;IACxD,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IACrD,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,oDAAoD;AACpD,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,wGAAwG;AACxG,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe,EAAE,IAAY,EAAE,IAAa;QACtD,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACvD,YAAY,OAAe,EAAE,IAAa;QACxC,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

package/dist/hash.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Compute the SHA-256 of any byte source and return it as a 0x-prefixed
+ * lowercase hex string — the exact format the BA Stamp API expects.
+ *
+ * Accepts `Uint8Array`, `ArrayBuffer`, `Blob` (browser/Bun), `Buffer`
+ * (Node), or anything that can be passed to `new Response()`. The
+ * computation is done locally via `crypto.subtle.digest`; the bytes
+ * never leave the caller's machine.
+ */
+export declare function hashFile(input: Uint8Array | ArrayBuffer | Blob | Buffer | ReadableStream<Uint8Array>): Promise<string>;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,GAC3E,OAAO,CAAC,MAAM,CAAC,CAsBjB"}

package/dist/hash.js

@@ -0,0 +1,34 @@
+/**
+ * Compute the SHA-256 of any byte source and return it as a 0x-prefixed
+ * lowercase hex string — the exact format the BA Stamp API expects.
+ *
+ * Accepts `Uint8Array`, `ArrayBuffer`, `Blob` (browser/Bun), `Buffer`
+ * (Node), or anything that can be passed to `new Response()`. The
+ * computation is done locally via `crypto.subtle.digest`; the bytes
+ * never leave the caller's machine.
+ */
+export async function hashFile(input) {
+    let bytes;
+    if (input instanceof ArrayBuffer) {
+        bytes = input;
+    }
+    else if (typeof Blob !== "undefined" && input instanceof Blob) {
+        bytes = await input.arrayBuffer();
+    }
+    else if (input instanceof ReadableStream) {
+        bytes = await new Response(input).arrayBuffer();
+    }
+    else if (ArrayBuffer.isView(input)) {
+        const view = input;
+        bytes = view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+    }
+    else {
+        throw new TypeError("hashFile: expected Uint8Array, ArrayBuffer, Blob, Buffer, or ReadableStream");
+    }
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    const hex = Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+    return "0x" + hex;
+}
+//# sourceMappingURL=hash.js.map

package/dist/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../src/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAA4E;IAE5E,IAAI,KAAkB,CAAC;IACvB,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,KAAK,GAAG,KAAK,CAAC;IAChB,CAAC;SAAM,IAAI,OAAO,IAAI,KAAK,WAAW,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAChE,KAAK,GAAG,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC;IACpC,CAAC;SAAM,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QAC3C,KAAK,GAAG,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,CAAC;SAAM,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,KAAmB,CAAC;QACjC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAgB,CAAC;IAC/F,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,SAAS,CACjB,6EAA6E,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;SAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,IAAI,GAAG,GAAG,CAAC;AACpB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BAStamp } from "./client.js";
+export { hashFile } from "./hash.js";
+export { BAStampError, BAStampInvalidRequestError, BAStampUnauthorizedError, BAStampNoCreditsError, BAStampNotFoundError, BAStampConflictError, BAStampRateLimitedError, } from "./errors.js";
+export type { Account, BatchInput, BitcoinAnchor, CertificateOptions, ClientOptions, ContentHash, CreateBatchResponse, CreateStampResponse, PolygonAnchor, RequestOptions, Stamp, StampInput, StampResult, StampStatus, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EACL,YAAY,EACZ,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,OAAO,EACP,UAAU,EACV,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,KAAK,EACL,UAAU,EACV,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { BAStamp } from "./client.js";
+export { hashFile } from "./hash.js";
+export { BAStampError, BAStampInvalidRequestError, BAStampUnauthorizedError, BAStampNoCreditsError, BAStampNotFoundError, BAStampConflictError, BAStampRateLimitedError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EACL,YAAY,EACZ,0BAA0B,EAC1B,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/retry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Decide whether an HTTP status code is worth retrying. Retryable: 408
+ * (Request Timeout), 429 (Rate Limited), 502/503/504 (transient server
+ * issues). Everything else — including 4xx that we shouldn't replay —
+ * fails immediately.
+ */
+export declare function shouldRetry(status: number): boolean;
+/**
+ * Exponential backoff with jitter. Attempt 0 → ~200ms, 1 → ~500ms,
+ * 2 → ~1000ms, 3 → ~2000ms, capped at ~5000ms. Jitter prevents
+ * thundering-herd retries when many clients see the same blip.
+ */
+export declare function backoffMs(attempt: number): number;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * RFC 9110: if the server includes a `Retry-After` header (either a
+ * delta-seconds integer or an HTTP-date), honor that instead of our
+ * computed backoff — within reason (cap at 60s).
+ */
+export declare function retryAfterMs(header: string | null): number | null;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAOjE"}

package/dist/retry.js

@@ -0,0 +1,51 @@
+/**
+ * Decide whether an HTTP status code is worth retrying. Retryable: 408
+ * (Request Timeout), 429 (Rate Limited), 502/503/504 (transient server
+ * issues). Everything else — including 4xx that we shouldn't replay —
+ * fails immediately.
+ */
+export function shouldRetry(status) {
+    return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
+}
+/**
+ * Exponential backoff with jitter. Attempt 0 → ~200ms, 1 → ~500ms,
+ * 2 → ~1000ms, 3 → ~2000ms, capped at ~5000ms. Jitter prevents
+ * thundering-herd retries when many clients see the same blip.
+ */
+export function backoffMs(attempt) {
+    const base = Math.min(5000, 200 * Math.pow(2.5, attempt));
+    const jitter = base * 0.3 * Math.random();
+    return Math.round(base + jitter);
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, ms);
+        if (signal) {
+            const onAbort = () => {
+                clearTimeout(t);
+                reject(new DOMException("Aborted", "AbortError"));
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+        }
+    });
+}
+/**
+ * RFC 9110: if the server includes a `Retry-After` header (either a
+ * delta-seconds integer or an HTTP-date), honor that instead of our
+ * computed backoff — within reason (cap at 60s).
+ */
+export function retryAfterMs(header) {
+    if (!header)
+        return null;
+    const asNumber = Number(header);
+    if (Number.isFinite(asNumber))
+        return Math.min(60_000, Math.max(0, asNumber * 1000));
+    const asDate = Date.parse(header);
+    if (Number.isFinite(asDate))
+        return Math.min(60_000, Math.max(0, asDate - Date.now()));
+    return null;
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;AAChG,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,YAAY,CAAC,CAAC,CAAC,CAAC;gBAChB,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;YACpD,CAAC,CAAC;YACF,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,EAAE,CAAC;;gBACzB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACvF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+/** 0x-prefixed lowercase SHA-256, exactly 66 chars long. */
+export type ContentHash = string;
+export interface StampInput {
+    /** SHA-256 of the file contents, 0x-prefixed lowercase. Get one with `hashFile()`. */
+    contentHash: ContentHash;
+    /** Original filename, stored as ownership metadata only. */
+    fileName?: string;
+    /** File size in bytes, metadata only. */
+    fileSize?: number;
+    /** MIME type, metadata only (e.g. `application/pdf`). */
+    mimeType?: string;
+    /** ISO 3166-1 alpha-2 (e.g. `IT`) — drives the legal framing on the certificate. */
+    jurisdiction?: string;
+    /** BCP-47 locale for the certificate (e.g. `it`, `en-US`). */
+    locale?: string;
+}
+export interface StampResult {
+    ownershipId: string;
+    stampId: string;
+    contentHash: ContentHash;
+    fileName: string | null;
+    /** True when this caller already owned the same hash — no credit was charged. */
+    duplicate: boolean;
+}
+export interface CreateStampResponse {
+    stamp: StampResult;
+    creditsCharged: number;
+}
+export interface BatchInput {
+    items: StampInput[];
+    /** Default jurisdiction applied to every item without its own. */
+    jurisdiction?: string;
+    /** Default locale stored on each ownership row. */
+    locale?: string;
+}
+export interface CreateBatchResponse {
+    results: StampResult[];
+    creditsCharged: number;
+    duplicateCount: number;
+}
+export type StampStatus = "pending" | "anchored";
+export interface BitcoinAnchor {
+    status: "pending" | "confirmed";
+    blockHeight: number | null;
+    blockTime: string | null;
+}
+export interface PolygonAnchor {
+    chain: "polygon" | "polygon-amoy";
+    merkleRoot: string;
+    txHash: string;
+    blockNumber: number;
+    blockTime: string;
+    bitcoin: BitcoinAnchor;
+}
+export interface Stamp {
+    contentHash: ContentHash;
+    status: StampStatus;
+    createdAt: string;
+    merkleProof: string[] | null;
+    anchor: PolygonAnchor | null;
+}
+export interface Account {
+    id: string;
+    email: string | null;
+    credits: number;
+}
+export interface CertificateOptions {
+    /** Locale of the certificate PDF (overrides stamp's stored locale). */
+    locale?: string;
+    /** Jurisdiction code for the legal framing block (overrides stamp's stored jurisdiction). */
+    jurisdiction?: string;
+}
+export interface RequestOptions {
+    /** Override the auto-generated Idempotency-Key for write operations. */
+    idempotencyKey?: string;
+    /** AbortSignal — call `controller.abort()` to cancel. */
+    signal?: AbortSignal;
+}
+export interface ClientOptions {
+    /** `ba_live_<32 hex chars>` from https://bastamp.com/account/api-keys */
+    apiKey: string;
+    /** Override the API root. Default: `https://bastamp.com`. */
+    baseUrl?: string;
+    /** Default fetch retry count on 429/5xx + network errors. Default: 3. */
+    maxRetries?: number;
+    /** Provide a custom fetch (e.g. for testing or non-browser/Node runtimes). */
+    fetch?: typeof globalThis.fetch;
+}
+export interface ApiErrorBody {
+    error: {
+        type: string;
+        message: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@bastamp/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the BA | Stamp REST API — anchor SHA-256 hashes on Polygon.",
+  "license": "MIT",
+  "author": "Aletheia Tech Ltd",
+  "homepage": "https://bastamp.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stamp-verify/bastamp-sdk-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stamp-verify/bastamp-sdk-ts/issues"
+  },
+  "keywords": [
+    "bastamp",
+    "blockchain",
+    "timestamp",
+    "polygon",
+    "sha256",
+    "merkle-proof",
+    "evidence",
+    "eidas",
+    "sdk",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  }
+}