@tesseraloyalty/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1136 @@
+/**
+ * The HTTP request core shared by every resource. It is runtime-self-contained —
+ * it uses only global Web standards (`fetch`, `Headers`, `AbortController`,
+ * `URLSearchParams`) so it runs unchanged on Node 20+, edge/Workers, Deno, and Bun.
+ * No `@loyalty/*` (or any runtime dependency) is imported.
+ *
+ * Responsibilities: bearer auth, JSON writes, idempotency-key passthrough, a
+ * per-attempt timeout, bounded retries with backoff (honoring `Retry-After`),
+ * `X-Request-Id` capture, tolerant success decoding, and envelope→`TesseraError`.
+ */
+/** A `fetch`-compatible function. `globalThis.fetch` satisfies this; a caller may inject their own. */
+type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+type QueryValue = string | number | boolean | null | undefined;
+interface RequestOptions {
+    /** Query params; `undefined`/`null` values are skipped. */
+    query?: Record<string, QueryValue>;
+    /** A JSON-serializable request body. Its presence sets `Content-Type: application/json`. */
+    body?: unknown;
+    /**
+     * A pre-serialized request body string, transmitted BYTE-FOR-BYTE (never re-serialized). This is
+     * the signed-bytes path for event ingestion (`POST /v1/events`): the caller signs the exact string
+     * it passes here, so re-serializing an object (`JSON.stringify` reordering keys / changing
+     * whitespace) can never invalidate that signature. Presence sets `Content-Type: application/json`
+     * (a rawBody IS a body, including an empty string). Takes precedence over `body` when both are set.
+     */
+    rawBody?: string;
+    /** Extra headers layered under the SDK's own (auth/content-type/idempotency win). */
+    headers?: Record<string, string>;
+    /** Sets the `Idempotency-Key` header; held constant across this call's retries. */
+    idempotencyKey?: string;
+    /**
+     * A hint for the publishable-vs-secret key GUARD added in a later ticket (TER-86).
+     * Accepted here for a stable signature; `request` itself is key-scope agnostic.
+     */
+    keyScope?: 'secret' | 'publishable' | 'any';
+}
+interface HttpCoreConfig {
+    /** The `/v1` base URL; trailing slashes are trimmed. */
+    baseUrl: string;
+    /** The resolved bearer token (secret or publishable key). */
+    token: string;
+    /** Per-attempt timeout in milliseconds. */
+    timeoutMs: number;
+    /** Maximum retry attempts on retriable failures (network / 5xx / 429). */
+    maxRetries: number;
+    /** The `fetch` implementation to use. */
+    fetchImpl: FetchLike;
+}
+declare class HttpCore {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(config: HttpCoreConfig);
+    /**
+     * Issue a request. On 2xx returns the tolerantly-parsed JSON body; on a non-2xx
+     * envelope throws a base `TesseraError`. Retries network errors / 5xx / 429 up to
+     * `maxRetries`; a per-attempt timeout is terminal (it means the call blew its budget).
+     */
+    request<T = unknown>(method: HttpMethod, path: string, opts?: RequestOptions): Promise<T>;
+    /** One fetch attempt, raced against a per-attempt timeout that aborts the request. */
+    private dispatch;
+    private buildUrl;
+    private buildHeaders;
+}
+
+/**
+ * The public rewards catalogue resource (`GET /v1/rewards`) — the ONE read a publishable key may
+ * make (non-personalized: no balance, no PII). The SDK owns its public wire↔camelCase types; the
+ * API body is snake_case (`apps/api` rewardsHandler + engine `toPublic`).
+ */
+/** A reward option's redemption constraints (camelCased from the API `constraints` block). */
+interface RewardOptionConstraints {
+    /** Minimum cart subtotal (minor units) required to redeem, or null for no minimum. */
+    minSpendCents: number | null;
+    /** Collection ids the option is scoped to (empty = unrestricted). */
+    eligibleCollectionIds: string[];
+    /** Product ids the option is scoped to (empty = unrestricted). */
+    eligibleProductIds: string[];
+    /** Whether this option may stack with another active redemption. */
+    stackable: boolean;
+    /** Per-customer redemption cap over a rolling window, or null for uncapped. */
+    perCustomerCap: {
+        count: number;
+        window: string;
+    } | null;
+    /** The tier key required to redeem, or null when ungated. */
+    tierGate: string | null;
+    /** Maximum discount value (minor units) the option may apply, or null for uncapped. */
+    valueCapCents: number | null;
+}
+/** One public (storefront-safe) catalogue option. */
+interface RewardOption {
+    id: string;
+    /** Redemption type (e.g. `fixed_discount`, `percentage_discount`, `free_product`). */
+    type: string;
+    label: string;
+    /** How the reward is fulfilled (e.g. `code`, `automatic`). */
+    mechanism: string;
+    /** Surfaces the option may be triggered on (e.g. `cart`, `checkout`). */
+    triggerSurfaces: string[];
+    /**
+     * The cost model, an open variant record keyed by `kind` (`fixed_points` / `percentage` /
+     * `points_per_unit_value` / `free`). Its inner keys are camelCased; kept loosely typed because
+     * the shape varies by kind. `costPoints` is the flattened flat cost for the common case.
+     */
+    costModel: Record<string, unknown>;
+    /** Flat point cost when known; null for variable (value-dependent) burn. */
+    costPoints: number | null;
+    constraints: RewardOptionConstraints;
+}
+/** The rewards catalogue: the merchant's points label + the list of options. */
+interface RewardsCatalogue {
+    /** The merchant's display label for points (e.g. `Stars`); defaults server-side to `points`. */
+    pointsLabel: string;
+    data: RewardOption[];
+}
+declare class RewardsResource {
+    private readonly http;
+    constructor(http: HttpCore);
+    /**
+     * Fetch the public rewards catalogue. `keyScope: 'publishable'` — allowed with a publishable OR
+     * a secret key (the one read a browser/publishable client may perform).
+     */
+    list(): Promise<RewardsCatalogue>;
+}
+
+/**
+ * The `client.redemptions` resource — the F16 burn-hold lifecycle over HTTP: `place` a hold →
+ * `finalize` (permanent burn) or `release` (abandon, restoring the reserved points), plus `get` to
+ * read a hold's status. Every endpoint is SECRET-scope (they write ledger state, never from a
+ * browser): a publishable-key client fails fast pre-network (better DX than a 403 round-trip),
+ * mirroring the customer write/read guards.
+ *
+ * Ledger correctness lives in the engine, not here — the SDK only CALLS the API. The engine's typed
+ * eligibility/balance errors surface as the mapped taxonomy classes (`insufficient_balance` →
+ * {@link InsufficientBalanceError} incl. `.shortfall`, `tier_gated`, `cap_reached`,
+ * `option_not_eligible`, unknown option → `not_found`) via the shared `errorFromEnvelope` factory.
+ *
+ * Channel discipline (design §5.2): the channel the customer lives on is validated through the
+ * client's `resolveChannel()` (the `channels` allowlist choke point) BEFORE any request, so a typo'd
+ * channel can never resolve the wrong (or a split) customer.
+ *
+ * Idempotency (doc 02 §3): `POST /v1/redemptions` REQUIRES an `Idempotency-Key`. When the caller
+ * does not supply one, `place` auto-generates a UUID and lets the HTTP core hold it constant across
+ * the automatic retries of THAT call — a retried place never double-charges the hold. A
+ * caller-supplied key is used verbatim (stable across the caller's own retries).
+ *
+ * The SDK owns its public camelCase types; the API bodies are snake_case (`apps/api` app.ts +
+ * `placeRedemptionSchema` / `finalizeRedemptionSchema`). Fields are mapped explicitly (precise
+ * types + drift detection).
+ */
+/** The `place` input — the option + the member's external id, plus optional cost/eligibility inputs. */
+interface PlaceRedemptionInput {
+    /** The reward option UUID to redeem. */
+    optionId: string;
+    /** The merchant-facing external id of the member redeeming (keyed on the resolved channel). */
+    externalId: string;
+    /**
+     * The channel this external id lives on. Resolved through the client's `resolveChannel()` — omit
+     * to use the client's bound channel, or name one (validated against the `channels` allowlist,
+     * throwing PRE-NETWORK on an out-of-vocabulary value).
+     */
+    channel?: string;
+    /** Cart subtotal (minor units) — feeds min-spend eligibility + percentage/value cost resolution. */
+    cartSubtotalCents?: number;
+    /** An explicit requested discount value (minor units); `null` clears any prior request. */
+    requestedValueCents?: number | null;
+    /** When the hold should expire — an ISO-8601 string or a `Date`. */
+    expiresAt?: string | Date;
+}
+/** Per-call options for `place`. */
+interface PlaceRedemptionOptions {
+    /**
+     * The `Idempotency-Key`. When omitted, `place` auto-generates a UUID (held constant across the
+     * automatic retries of this call). Supply your own to make a place stable across YOUR retries.
+     */
+    idempotencyKey?: string;
+}
+/** The placed-hold result (`POST /v1/redemptions`, state `held`). */
+interface RedemptionResult {
+    redemptionId: string;
+    customerUuid: string;
+    optionId: string;
+    /** The points reserved by the hold (minor points units). */
+    amount: number;
+    /** The resolved discount value (minor currency units) the redemption applies. */
+    discountValueCents: number;
+    /** How the reward is fulfilled (e.g. `code`, `automatic`). */
+    mechanism: string;
+    /** The hold state (`held` on placement). */
+    state: string;
+    /** When the hold expires (ISO-8601), or null when it does not. */
+    expiresAt: string | null;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+}
+/** A redemption hold's status (`GET /v1/redemptions/:id`). */
+interface RedemptionStatus {
+    redemptionId: string;
+    /** The hold state (`held` | `finalized` | `released`). */
+    state: string;
+    amount: number;
+}
+/** The `finalize` input — the order that consumed the redemption (its burn provenance). */
+interface FinalizeRedemptionInput {
+    /** Which external system consumed the redemption (e.g. `shopify`). */
+    sourceChannel: string;
+    /** The external object id (e.g. the order id) the burn is stamped with. */
+    sourceRef: string;
+}
+/** The `finalize` result (permanent burn). */
+interface FinalizeRedemptionResult {
+    redemptionId: string;
+    state: 'finalized';
+}
+/** The `release` result (hold abandoned; reserved points restored). */
+interface ReleaseRedemptionResult {
+    redemptionId: string;
+    state: 'released';
+    /** The member's `available` after the reserved points were restored. */
+    available: number;
+}
+/**
+ * A placed redemption augmented with `.finalize()` / `.release()` convenience methods bound to its
+ * id — what `member.redeem(...)` returns so the storefront flow chains (`place → finalize|release`)
+ * without threading the redemption id back through the resource.
+ */
+interface RedemptionHandle extends RedemptionResult {
+    /** Finalize this hold (permanent burn), stamped with the consuming order's provenance. */
+    finalize(input: FinalizeRedemptionInput): Promise<FinalizeRedemptionResult>;
+    /** Release this hold (abandon it; restore the reserved points). */
+    release(): Promise<ReleaseRedemptionResult>;
+}
+/** Everything a {@link RedemptionsResource} needs from its parent client, passed explicitly (no cycle). */
+interface RedemptionsDeps {
+    http: HttpCore;
+    keyType: KeyType;
+    /** The client's channel resolver — validates a channel against the `channels` allowlist. */
+    resolveChannel: (channel?: string) => string;
+}
+declare class RedemptionsResource {
+    private readonly http;
+    private readonly keyType;
+    private readonly resolveChannel;
+    constructor(deps: RedemptionsDeps);
+    /** Fail fast pre-network when a secret-scope operation is attempted with a publishable key. */
+    private requireSecret;
+    /**
+     * Place a redemption hold (`POST /v1/redemptions`). The channel is resolved through the client
+     * (bound default when omitted, else validated against the allowlist — a PRE-NETWORK throw on an
+     * out-of-vocabulary value). An `Idempotency-Key` is REQUIRED by the API; when `opts.idempotencyKey`
+     * is absent the SDK auto-generates a UUID and holds it constant across this call's retries.
+     *
+     * Not `async` so the channel-allowlist check throws SYNCHRONOUSLY before any transport work.
+     */
+    place(input: PlaceRedemptionInput, opts?: PlaceRedemptionOptions): Promise<RedemptionResult>;
+    private sendPlace;
+    /**
+     * Read a redemption hold's status (`GET /v1/redemptions/:id`). Tenant-scoped: 404 →
+     * {@link RedemptionNotFoundError} (no cross-tenant existence leak).
+     */
+    get(id: string): Promise<RedemptionStatus>;
+    /**
+     * Finalize a hold — the permanent burn (`POST /v1/redemptions/:id/finalize`). Idempotent on the
+     * hold: an already-finalized hold replays; finalizing a RELEASED (terminal) hold →
+     * {@link HoldAlreadyReleasedError} (409). `sourceChannel`/`sourceRef` stamp the burn's provenance.
+     */
+    finalize(id: string, input: FinalizeRedemptionInput): Promise<FinalizeRedemptionResult>;
+    /**
+     * Release a hold — abandon it and restore the reserved points (`POST /v1/redemptions/:id/release`).
+     * Idempotent. Returns the member's `available` after the restore.
+     */
+    release(id: string): Promise<ReleaseRedemptionResult>;
+    /**
+     * @internal Wrap a placed-hold result in a {@link RedemptionHandle} — the same fields plus
+     * `.finalize()` / `.release()` bound to this resource + the redemption id. Consumed by
+     * `member.redeem(...)`; not part of the documented public surface.
+     */
+    toHandle(result: RedemptionResult): RedemptionHandle;
+}
+
+/**
+ * The `(channel, externalId)`-keyed member handle — the ergonomic core of the read surface. Its
+ * channel is BOUND (from the client's `resolveChannel()`), never a per-call arg, so the
+ * "`shopify` here, `shoify` there" identity split is structurally impossible. All four reads are
+ * SECRET-scope; a publishable-key client fails fast pre-network (better DX than a 403 round-trip).
+ *
+ * The SDK owns its public camelCase types; the API bodies are snake_case (`apps/api`). Structured
+ * reads map fields explicitly (precise types + drift detection).
+ */
+/** The pseudonymous member profile (`GET /v1/customers/:channel/:externalId`). */
+interface MemberProfile {
+    customerUuid: string;
+    channel: string;
+    externalId: string;
+    /** ISO-8601 creation timestamp, or null when no customer row exists for the pair. */
+    createdAt: string | null;
+}
+/** A member's balances across the two currencies + the redemption `available` (`.../balance`). */
+interface MemberBalance {
+    customerUuid: string;
+    /** The merchant's display label for points. */
+    pointsLabel: string;
+    /** Confirmed (spendable) points. */
+    spendableBalance: number;
+    /** Accruing points not yet matured (visible, not spendable). */
+    pendingSpendable: number;
+    /** Cumulative qualifying credits (the status-track currency). */
+    qualifyingBalance: number;
+    /** Points reserved by in-flight redemption holds. */
+    activeHolds: number;
+    /** Outstanding clawbacks (post-refund debt recovered on the next earn). */
+    clawbacksOutstanding: number;
+    /** `confirmed − activeHolds − clawbacksOutstanding` — what may be redeemed now (may be negative). */
+    available: number;
+}
+/** A member's current tier (camelCased from the `current_tier` block). */
+interface MemberTier {
+    key: string;
+    name: string;
+    /** The tier's earn multiplier. */
+    earnMultiplier: number;
+    /** Reward-eligibility tags carried on the tier (config round-tripped; enforcement is deferred). */
+    rewardEligibility: string[];
+}
+/** Progress toward the next tier + the current hold threshold (camelCased `qualifying_progress`). */
+interface QualifyingProgress {
+    /** The member's current qualifying total. */
+    current: number;
+    /** Qualifying needed to HOLD the current tier this period, or null when no tier applies. */
+    holdThreshold: number | null;
+    /** The next tier's key, or null at the top of the ladder / with no program. */
+    nextTierKey: string | null;
+    /** Qualifying needed to reach the next tier, or null when there is none. */
+    nextQualifyThreshold: number | null;
+}
+/** A member's tier status + progress (`.../status`). Every field is null when no program applies. */
+interface MemberStatus {
+    customerUuid: string;
+    currentTier: MemberTier | null;
+    effectiveTierKey: string | null;
+    periodStart: string | null;
+    periodEnd: string | null;
+    requalificationState: string | null;
+    graceDeadline: string | null;
+    qualifyingProgress: QualifyingProgress;
+}
+/** One ledger history entry (`.../history` data item), camelCased. */
+interface HistoryEntry {
+    id: string;
+    /** entry type: earn | maturation | burn | expiry | adjustment | reversal | clawback. */
+    type: string;
+    currency: string;
+    /** Signed minor units: positive = credit, negative = debit. */
+    amount: number;
+    state: string;
+    /** Which external system triggered the entry, or null. */
+    sourceChannel: string | null;
+    /** The external object id (e.g. order id), or null. */
+    sourceRef: string | null;
+    /** The originating event id, or null. */
+    sourceEventId: string | null;
+    createdAt: string;
+}
+/** Page cursor metadata for a single history page. */
+interface HistoryPageInfo {
+    /** The opaque cursor for the NEXT page, or null when there are no more pages. */
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** One page of history: the entries + cursor info (what a single `await member.history()` yields). */
+interface HistoryPage {
+    data: HistoryEntry[];
+    page: HistoryPageInfo;
+}
+/** Options for a history read. `types` is joined into the API's comma-separated `type` param. */
+interface HistoryOptions {
+    /** Page size (1–100). */
+    limit?: number;
+    /** An opaque cursor to start from (a prior page's `nextCursor`). */
+    cursor?: string;
+    /** Restrict to these entry types (joined into `?type=a,b`). */
+    types?: string[];
+    /** Only entries at/after this ISO-8601 timestamp (or a `Date`). */
+    since?: string | Date;
+    /** Only entries at/before this ISO-8601 timestamp (or a `Date`). */
+    until?: string | Date;
+}
+/** Per-member overrides (currently only a channel override, validated vs the client allowlist). */
+interface MemberOptions {
+    /** Override the client's bound channel for THIS handle (validated against the allowlist). */
+    channel?: string;
+}
+/**
+ * The `member.redeem(...)` input — a `place` request with the member's `externalId` + channel already
+ * bound by the handle (so only the option + optional cost/eligibility inputs are passed here).
+ */
+interface MemberRedeemInput {
+    /** The reward option UUID to redeem. */
+    optionId: string;
+    /** Cart subtotal (minor units) — feeds min-spend eligibility + percentage/value cost resolution. */
+    cartSubtotalCents?: number;
+    /** An explicit requested discount value (minor units); `null` clears any prior request. */
+    requestedValueCents?: number | null;
+    /** When the hold should expire — an ISO-8601 string or a `Date`. */
+    expiresAt?: string | Date;
+}
+/**
+ * The history pager. `member.history(opts)` returns one synchronously; it is BOTH:
+ *   - an async-iterable that auto-follows the cursor across every page (`for await (…)`), and
+ *   - awaitable (`PromiseLike`) to resolve the FIRST page as a {@link HistoryPage} with
+ *     `.data` / `.page`, for simple single-page use.
+ * `for await` uses `Symbol.asyncIterator` (never `.then`), so the two forms never collide.
+ */
+declare class HistoryPager implements AsyncIterable<HistoryEntry>, PromiseLike<HistoryPage> {
+    private readonly fetchPage;
+    constructor(fetchPage: (cursor?: string) => Promise<HistoryPage>);
+    [Symbol.asyncIterator](): AsyncIterator<HistoryEntry>;
+    then<TResult1 = HistoryPage, TResult2 = never>(onfulfilled?: ((value: HistoryPage) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+/** Everything a {@link MemberHandle} needs from its parent client, passed explicitly (no cycle). */
+interface MemberDeps {
+    http: HttpCore;
+    keyType: KeyType;
+    channel: string;
+    externalId: string;
+    /** The client's redemptions resource — powers `member.redeem(...)` (the write sugar). */
+    redemptions: RedemptionsResource;
+}
+declare class MemberHandle {
+    /** The channel bound to this handle (from the client's `resolveChannel()`). */
+    readonly channel: string;
+    /** The merchant-facing external id this handle reads. */
+    readonly externalId: string;
+    private readonly http;
+    private readonly keyType;
+    private readonly redemptions;
+    constructor(deps: MemberDeps);
+    /** The `/customers/:channel/:externalId` path prefix (both segments URL-encoded). */
+    private base;
+    /** Fail fast pre-network when a secret-scope read is attempted with a publishable key. */
+    private requireSecret;
+    /** The pseudonymous member profile (identity + channel binding; no PII). */
+    get(): Promise<MemberProfile>;
+    /** The member's balances (spendable / pending / qualifying / holds / available). */
+    balance(): Promise<MemberBalance>;
+    /** The member's tier status + progress toward the next tier. */
+    status(): Promise<MemberStatus>;
+    /**
+     * The member's points history. Returns a {@link HistoryPager}: iterate it with `for await` to
+     * auto-follow the cursor across all pages, or `await` it for just the first {@link HistoryPage}
+     * (`.data` / `.page`). `opts.cursor`, if given, is the starting page for the awaited-first-page
+     * form; the iterator always starts fresh and follows the cursor from there.
+     */
+    history(opts?: HistoryOptions): HistoryPager;
+    /**
+     * Place a redemption hold for THIS member (`POST /v1/redemptions`) — sugar over
+     * `client.redemptions.place(...)` with the handle's `externalId` + bound channel supplied for you.
+     * Returns a {@link RedemptionHandle}: the placed-hold result plus `.finalize({ sourceChannel,
+     * sourceRef })` / `.release()` bound to it, so the storefront flow chains cleanly. Secret-scope
+     * (delegated to the redemptions resource); a publishable-key client rejects pre-network.
+     */
+    redeem(input: MemberRedeemInput, opts?: PlaceRedemptionOptions): Promise<RedemptionHandle>;
+}
+
+/**
+ * The `client.customers` resource — the customer/identity WRITE + server-side PII surface
+ * (`upsert` / `update` / `getPii` / `linkChannel` / `unlinkChannel`). Every endpoint here is
+ * SECRET-scope: a publishable-key client fails fast pre-network (better DX than a 403 round-trip),
+ * mirroring the read handle's guard.
+ *
+ * Channel discipline (design §5.2): the channel a customer lives on is validated through the
+ * client's `resolveChannel()` (the `channels` allowlist choke point) — `upsert` resolves its
+ * (optional) input channel to the bound default, and `linkChannel` validates its TARGET channel —
+ * both BEFORE any request, so a typo'd channel can never split identity/ledger.
+ *
+ * The SDK owns its public camelCase types; the API bodies are snake_case (`apps/api` app.ts, the
+ * `toProfileFields` / `piiToWire` helpers). Fields are mapped explicitly (precise types + drift
+ * detection), and `null` is preserved as an intentional CLEAR (never dropped).
+ */
+/** A per-channel marketing-consent state (`opted_in` / `opted_out` / `unset`). */
+type ConsentState = 'opted_in' | 'opted_out' | 'unset';
+/** Marketing-consent flags + when they last changed (camelCased from `marketing_consent`). */
+interface MarketingConsent {
+    email?: ConsentState;
+    sms?: ConsentState;
+    /** ISO-8601 timestamp the consent last changed. */
+    updatedAt?: string;
+}
+/**
+ * The mutable PII field set shared by `upsert` and `update`. A `null` value CLEARS the field
+ * (server-side); an ABSENT field is left untouched (merge semantics). Semantic validation
+ * (email/birthday/locale) is enforced server-side and surfaces as a `ProfileValidationError` (422).
+ */
+interface CustomerProfileFields {
+    email?: string | null;
+    name?: string | null;
+    birthday?: string | null;
+    locale?: string | null;
+    socialHandles?: Record<string, string> | null;
+    marketingConsent?: MarketingConsent | null;
+}
+/** The `upsert` input — the profile fields plus the REQUIRED `externalId` and an optional channel. */
+interface CustomerUpsertInput extends CustomerProfileFields {
+    /** The merchant-facing external id keying this customer on its channel. Required. */
+    externalId: string;
+    /**
+     * The channel this external id lives on. Resolved through the client's `resolveChannel()` — omit
+     * to use the client's bound channel, or name one (validated against the `channels` allowlist,
+     * throwing PRE-NETWORK on an out-of-vocabulary value).
+     */
+    channel?: string;
+}
+/** Per-call options for `upsert`. */
+interface CustomerUpsertOptions {
+    /** Sets the `Idempotency-Key` header for a safe create-or-update retry. */
+    idempotencyKey?: string;
+}
+/** The `upsert` result: the resolved customer + whether this call CREATED it (201) or updated it (200). */
+interface CustomerUpsertResult {
+    customerUuid: string;
+    channel: string;
+    externalId: string;
+    /** `true` when this call created the customer (HTTP 201); `false` on an update (HTTP 200). */
+    created: boolean;
+    /** ISO-8601 timestamp of the resulting row. */
+    updatedAt: string;
+}
+/** Decrypted server-side PII (`getPii` / the `update` response). Absent keys were never set. */
+interface CustomerPii {
+    customerUuid: string;
+    email?: string;
+    name?: string;
+    birthday?: string;
+    locale?: string;
+    socialHandles?: Record<string, string>;
+    marketingConsent?: MarketingConsent;
+    /** ISO-8601 timestamp the identity row last changed. */
+    updatedAt?: string;
+}
+/** The `linkChannel` input — the TARGET channel + external id to bind to an existing customer. */
+interface LinkChannelInput {
+    /** The channel to link. Validated against the client's `channels` allowlist pre-network. */
+    channel: string;
+    externalId: string;
+}
+/** The `linkChannel` result. */
+interface LinkChannelResult {
+    customerUuid: string;
+    /** How the link was created (e.g. `manual`). */
+    linkedVia: string;
+    /** The resulting link status (e.g. `active`). */
+    status: string;
+}
+/** The `unlinkChannel` result. */
+interface UnlinkChannelResult {
+    /** The resulting link status (e.g. `unlinked`). */
+    status: string;
+}
+/** Everything a {@link CustomersResource} needs from its parent client, passed explicitly (no cycle). */
+interface CustomersDeps {
+    http: HttpCore;
+    keyType: KeyType;
+    /** The client's channel resolver — validates a channel against the `channels` allowlist. */
+    resolveChannel: (channel?: string) => string;
+}
+declare class CustomersResource {
+    private readonly http;
+    private readonly keyType;
+    private readonly resolveChannel;
+    constructor(deps: CustomersDeps);
+    /** Fail fast pre-network when a secret-scope write is attempted with a publishable key. */
+    private requireSecret;
+    /**
+     * Create-or-update a customer profile (`POST /v1/customers`). Returns `created: true` on a create
+     * (201) or `false` on an update (200) — natural idempotency keys on the resolved `(channel,
+     * externalId)`. The channel is resolved through the client (bound default when omitted, else
+     * validated against the allowlist — a PRE-NETWORK throw on an out-of-vocabulary value). Pass
+     * `opts.idempotencyKey` to make a retry safe.
+     *
+     * Not `async` so the channel-allowlist check throws SYNCHRONOUSLY before any transport work.
+     */
+    upsert(input: CustomerUpsertInput, opts?: CustomerUpsertOptions): Promise<CustomerUpsertResult>;
+    private sendUpsert;
+    /**
+     * Partial-update a customer's PII (`PATCH /v1/customers/:ref`). `ref` is a customer UUID or an
+     * external id (on the `api` channel). A `null` field CLEARS it; an absent field is untouched
+     * (merge). Returns the decrypted PII (camelCase). 404 → `CustomerNotFoundError`.
+     */
+    update(ref: string, fields: CustomerProfileFields): Promise<CustomerPii>;
+    /**
+     * Read a customer's decrypted PII by UUID (`GET /v1/customers/:uuid`). Secret-only. 404 →
+     * `CustomerNotFoundError` (no cross-tenant existence leak).
+     */
+    getPii(uuid: string): Promise<CustomerPii>;
+    /**
+     * Manually link a `(channel, externalId)` pair to an existing customer (`POST
+     * /v1/customers/:uuid/links`). The TARGET channel is validated against the client's `channels`
+     * allowlist PRE-NETWORK (a typo cannot split identity). 404 → `CustomerNotFoundError`.
+     *
+     * Not `async` so the channel-allowlist check throws SYNCHRONOUSLY before any transport work.
+     */
+    linkChannel(uuid: string, input: LinkChannelInput): Promise<LinkChannelResult>;
+    private sendLink;
+    /**
+     * Manually unlink a `(channel, externalId)` pair (`DELETE
+     * /v1/customers/:uuid/links/:channel/:externalId`). Idempotent. The `:uuid` scopes/authorizes the
+     * call; the pair identifies the specific link to remove.
+     */
+    unlinkChannel(uuid: string, channel: string, externalId: string): Promise<UnlinkChannelResult>;
+}
+
+/**
+ * The `client.events` resource — the SIGNED, idempotent front door for inbound events
+ * (`POST /v1/events`). A merchant/connector constructs an event envelope (a purchase or refund) and
+ * the SDK HMAC-signs it and posts it; the engine authenticates the signature, dedupes, resolves the
+ * customer, and enqueues earn/refund. Ledger correctness lives in the engine — this resource only
+ * signs and transmits.
+ *
+ * ## The sign==sent invariant (the whole risk of this resource)
+ * The signature covers the LITERAL request body bytes (`${timestamp}.${rawBody}`, mirrored from
+ * `packages/engine/src/crypto.ts`). So the bytes signed MUST equal the bytes sent — a re-serialized
+ * body (key reordering / whitespace) invalidates the signature and the API 401s. This resource
+ * guarantees byte-identity structurally:
+ *   1. Serialize the wire payload to a raw JSON string EXACTLY ONCE (`JSON.stringify`).
+ *   2. Sign THAT string (`signEventBody(rawBody, signingSecret)`).
+ *   3. Transmit THAT SAME string verbatim via the HTTP core's `rawBody` path — which never
+ *      re-serializes (contrast the object `body` path, which `JSON.stringify`s) — with the three
+ *      returned signing headers.
+ * The one string produced in (1) is the one thing signed and the one thing sent; there is no second
+ * serialization anywhere in between.
+ *
+ * ## Guards (both PRE-NETWORK)
+ *   - SECRET-scope: signed ingestion is a server-to-server write; a publishable-key client fails fast
+ *     (mirrors the customer/redemption write guards).
+ *   - `signingSecret` REQUIRED: signing needs the per-tenant connector secret (`whsec_...`), which is
+ *     SEPARATE from the bearer API key. A client constructed without one throws a specific config
+ *     error before any request — never a silent unsigned POST that the API would only reject as a 401.
+ *
+ * The SDK owns its public camelCase types; the API request body is snake_case (`ingestEventSchema` in
+ * `packages/shared`, parsed by `apps/api` `POST /v1/events`). Fields are mapped explicitly; the
+ * top-level wire is `.strict()`, so only known keys are emitted. `amount` is intentionally open (the
+ * engine reads the known bases and strips the rest), so extra breakdown fields are forwarded verbatim.
+ */
+/**
+ * The event types the operations API accepts at its boundary. Phase 1 INGESTS `purchase` and
+ * `refund` (others resolve to an `unsupported_event_type` 422 → {@link UnsupportedEventTypeError});
+ * the wider vocabulary is typed here for forward-compatibility with the server schema.
+ */
+type EventType = 'purchase' | 'refund' | 'referral' | 'review' | 'profile';
+/**
+ * The monetary breakdown for an event. The named fields are what the engine reads (purchase earn
+ * bases; refund `refundedBase`/`orderBase`, minor units). It is deliberately OPEN — connectors
+ * legitimately attach extra breakdown fields (tax/shipping/discounts/fees) which the engine strips;
+ * any extra key is forwarded verbatim (use the wire snake_case name for a field you want preserved).
+ */
+interface EventAmount {
+    /** Gross order total, minor units. */
+    gross?: number;
+    /** Order total net of tax + shipping, minor units. */
+    netOfTaxShipping?: number;
+    /** Order total after discounts, minor units. */
+    finalAfterDiscounts?: number;
+    /** ISO-4217 currency code (3 letters). */
+    currency?: string;
+    /** Refund events: this refund's amount, minor units (same denomination as the earn base). */
+    refundedBase?: number;
+    /** Refund events: the ORIGINAL order's earn base, minor units (pinned on the first refund). */
+    orderBase?: number;
+    /** Extra breakdown fields, forwarded verbatim; the engine reads only the known bases. */
+    [extra: string]: number | string | undefined;
+}
+/**
+ * The event envelope a merchant/connector constructs to ingest. `type` + the core provenance
+ * (`channel`, `externalId`, `sourceRef`, `idempotencyKey`, `occurredAt`) are always required; the
+ * rest are type-specific (purchase: `trigger`/`orderRef`/`amount` earn bases; refund:
+ * `orderRef`/`amount.refundedBase`/`amount.orderBase`). `(channel, externalId)` resolves the
+ * pseudonymous customer server-side (never a bare external id, invariant #1).
+ */
+interface IngestEventInput {
+    /** The event type (`purchase` | `refund` in Phase 1). */
+    type: EventType;
+    /** The channel this event originated on (also the customer-resolution + provenance axis). */
+    channel: string;
+    /** The merchant-facing external id keying the customer on `channel`. */
+    externalId: string;
+    /** The external object id (e.g. the order id) — the business-dedup axis + ledger provenance. */
+    sourceRef: string;
+    /**
+     * The idempotency key (namespace the channel in, e.g. `shopify:ord_5512-purchase`). This value in
+     * the SIGNED BODY is the canonical dedup key; the `Idempotency-Key` header, when sent, must echo it.
+     */
+    idempotencyKey: string;
+    /** When the event occurred — an ISO-8601 string or a `Date` (serialized to ISO on the wire). */
+    occurredAt: string | Date;
+    /** Optional defense-in-depth tenant id; when present it MUST equal the authenticated key's tenant. */
+    tenant?: string;
+    /** The earn trigger (e.g. `orders/paid`), captured for the Earn Engine. */
+    trigger?: string;
+    /** The originating order id (required for a `refund`; maps a refund to the original accrual). */
+    orderRef?: string;
+    /** The monetary breakdown (earn bases for a purchase; refund/order bases for a refund). */
+    amount?: EventAmount;
+    /** Optional email carried for identity resolution (feature 27). */
+    email?: string;
+    /** Optional phone carried for identity resolution (feature 27). */
+    phone?: string;
+}
+/** Per-call options for `ingest`. */
+interface IngestEventOptions {
+    /**
+     * Sets the `Idempotency-Key` HEADER. Optional: the canonical dedup key is the SIGNED BODY's
+     * `idempotencyKey`. When provided it MUST equal that body value (the API rejects a mismatch with
+     * `invalid_payload`); use it only to make transport-layer replay explicit.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * The result of ingesting an event (`POST /v1/events`). `status` is `accepted` on the first sighting
+ * (HTTP 201) or `duplicate` on a deduped redelivery (HTTP 200). On a duplicate, `customerCreated` and
+ * `enqueued` are `false` (no new customer, no new earn job).
+ */
+interface IngestEventResult {
+    eventId: string;
+    customerId: string;
+    channel: string;
+    sourceRef: string;
+    type: string;
+    /** `accepted` (201, first sighting) | `duplicate` (200, deduped redelivery). */
+    status: 'accepted' | 'duplicate';
+    /** `true` when Identity Resolution minted a new customer for this event. */
+    customerCreated: boolean;
+    /** How the customer was linked (`channel` today; email/phone match once feature 27 lands). */
+    linkedVia: string;
+    /** `true` when this call enqueued an earn job (only on `accepted`; `false` on `duplicate`). */
+    enqueued: boolean;
+}
+/** Everything an {@link EventsResource} needs from its parent client, passed explicitly (no cycle). */
+interface EventsDeps {
+    http: HttpCore;
+    keyType: KeyType;
+    /** The per-tenant connector signing secret (`whsec_...`); `undefined` when not configured. */
+    signingSecret: string | undefined;
+}
+declare class EventsResource {
+    private readonly http;
+    private readonly keyType;
+    private readonly signingSecret;
+    constructor(deps: EventsDeps);
+    /** Fail fast pre-network when signed ingestion is attempted with a publishable key. */
+    private requireSecret;
+    /**
+     * Fail fast pre-network when no signing secret is configured — signing is impossible without the
+     * per-tenant connector secret (`whsec_...`), which is SEPARATE from the bearer API key. Throwing
+     * here (rather than sending an unsigned body the API would 401) gives a clear, specific diagnosis.
+     */
+    private requireSigningSecret;
+    /**
+     * Ingest a signed event (`POST /v1/events`). SECRET-scope + requires a `signingSecret` (both fail
+     * fast pre-network). Serializes the payload to a raw JSON string ONCE, HMAC-signs THAT string, and
+     * transmits THE SAME string verbatim with the `X-Loyalty-Signature`/`-Timestamp`/`-Nonce` headers —
+     * so the bytes signed are byte-identical to the bytes sent (see the resource doc). Returns the
+     * ingestion result mapped to camelCase (`accepted` 201 / `duplicate` 200).
+     */
+    ingest(input: IngestEventInput, opts?: IngestEventOptions): Promise<IngestEventResult>;
+}
+
+/**
+ * `TesseraClient` — the SDK entry point. It validates + resolves configuration
+ * (exactly one of secret/publishable key → the bearer token), binds the channel,
+ * holds the signing / transport settings later tickets consume, and wires the HTTP core.
+ *
+ * ## Channel binding (the typo-split defense — design §5.2)
+ * Customer-scoped operations take NO per-call `channel`: it is bound once, here, so
+ * the "`'shopify'` here, `'shoify'` there" identity/ledger split is structurally
+ * impossible. Three layers, all enforced by this class:
+ *   1. **Bound channel** — set once (default `'api'`); `withChannel(x)` derives a
+ *      channel-scoped client for the rare legitimate multi-channel case.
+ *   2. **`channels` allowlist** — if provided, the bound channel, every `withChannel`
+ *      target, and every `resolveChannel(target)` (used later by `linkChannel`) must
+ *      be a member, else an immediate PRE-NETWORK throw listing the known channels.
+ *   3. **TS union** — the client is generic over the channel literal union `Ch`,
+ *      inferred from a `channels: [...] as const`, so a typo fails to COMPILE.
+ *
+ * The publishable-vs-secret per-endpoint guard is still deferred (a later ticket);
+ * the resource groups and the member handle land later and read the bound channel
+ * via `resolveChannel()`.
+ */
+type KeyType = 'secret' | 'publishable';
+/**
+ * Configuration for {@link TesseraClient}. Generic over the channel literal union
+ * `Ch`, which is inferred from a `channels: [...] as const` allowlist so that a typo
+ * in `channel` fails to compile. When `channels` is omitted, `Ch` widens to `string`
+ * (any channel is accepted).
+ */
+interface TesseraClientConfig<Ch extends string = string> {
+    /** The secret bearer key — unlocks every operation. Provide exactly one of secret/publishable. */
+    secretKey?: string;
+    /** The publishable bearer key — catalogue-only. Provide exactly one of secret/publishable. */
+    publishableKey?: string;
+    /** The per-tenant connector HMAC secret (events signing, TER-87). Never equal to the bearer key. */
+    signingSecret?: string;
+    /**
+     * The channel bound to customer-scoped operations. Defaults to `'api'`. Must be a
+     * member of `channels` when that allowlist is provided. Wrapped in `NoInfer` so the
+     * channel union is driven ONLY by `channels` — a lone `channel` never narrows `Ch`.
+     */
+    channel?: NoInfer<Ch>;
+    /**
+     * Optional channel vocabulary. When provided it is enforced two ways: at runtime
+     * (an out-of-list channel throws pre-network) and, via `as const`, at compile time
+     * (`Ch` narrows to the literal union so `withChannel('typo')` is a type error).
+     */
+    channels?: readonly Ch[];
+    /** The `/v1` base URL. Defaults to the production constant; overridable for local/dev. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Maximum retries on retriable failures (network / 5xx / 429). Default 2. */
+    maxRetries?: number;
+    /** A custom `fetch` implementation. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+}
+declare class TesseraClient<Ch extends string = string> {
+    /** Whether this client authenticates with a secret or publishable key. */
+    readonly keyType: KeyType;
+    /** The channel bound to customer-scoped operations (default `'api'`). */
+    readonly channel: Ch;
+    /** The optional channel allowlist. When set, every channel used must be a member. */
+    readonly channels?: readonly Ch[];
+    /** The per-tenant events signing secret, if configured (used by TER-87). */
+    readonly signingSecret?: string;
+    /** The resolved `/v1` base URL. */
+    readonly baseUrl: string;
+    /** The per-request timeout in milliseconds. */
+    readonly timeoutMs: number;
+    /** The maximum retry count on retriable failures. */
+    readonly maxRetries: number;
+    /**
+     * @internal The shared HTTP transport. Resource groups (later tickets) issue their
+     * requests through this; it is not part of the documented public surface.
+     */
+    readonly http: HttpCore;
+    constructor(config: TesseraClientConfig<Ch>);
+    /**
+     * Derive a NEW client bound to `channel`, for the rare legitimate multi-channel
+     * case. It SHARES this client's auth, transport (the very same {@link HttpCore}
+     * instance — never rebuilt), signing secret, and `channels` allowlist; the original
+     * is never mutated. Throws pre-network (before any request) if `channel` is outside
+     * the allowlist. `channel` is typed against `Ch`, so a typo fails to compile.
+     */
+    withChannel(channel: Ch): TesseraClient<Ch>;
+    /**
+     * The public rewards catalogue resource (`GET /v1/rewards`). Allowed with a publishable OR a
+     * secret key — the one read a storefront/browser client may make. A fresh (stateless) resource
+     * is returned per access so channel-scoped clones (`withChannel`) inherit it for free.
+     */
+    get rewards(): RewardsResource;
+    /**
+     * The customer/identity WRITE + server-side PII resource (`upsert` / `update` / `getPii` /
+     * `linkChannel` / `unlinkChannel`). Every operation is secret-scope; a publishable-key client
+     * fails fast pre-network. A fresh (stateless) resource is returned per access, wired with the
+     * shared transport + this client's channel resolver so `withChannel` clones inherit it correctly.
+     */
+    get customers(): CustomersResource;
+    /**
+     * The redemption burn-hold lifecycle resource (`place` / `get` / `finalize` / `release`). Every
+     * operation is secret-scope; a publishable-key client fails fast pre-network. A fresh (stateless)
+     * resource is returned per access, wired with the shared transport + this client's channel
+     * resolver so `withChannel` clones inherit it correctly.
+     */
+    get redemptions(): RedemptionsResource;
+    /**
+     * The signed event-ingestion resource (`ingest` → `POST /v1/events`). Every ingestion is
+     * SECRET-scope AND requires a `signingSecret` (the per-tenant connector HMAC secret, separate from
+     * the bearer key) — both fail fast pre-network. A fresh (stateless) resource is returned per access,
+     * wired with the shared transport + this client's signing secret so `withChannel` clones inherit it.
+     */
+    get events(): EventsResource;
+    /**
+     * Open a {@link MemberHandle} for a member identified by `externalId` on this client's bound
+     * channel — the ergonomic `(channel, externalId)`-keyed read + redeem surface (`get` / `balance` /
+     * `status` / `history` / `redeem`). The channel comes from {@link resolveChannel}: omit
+     * `opts.channel` to use the bound channel, or pass `opts.channel` to override it (validated against
+     * the `channels` allowlist, throwing PRE-NETWORK on an out-of-vocabulary value). All member
+     * operations are secret-scope; a publishable-key client fails fast when one is attempted.
+     */
+    member(externalId: string, opts?: MemberOptions): MemberHandle;
+    /**
+     * @internal Resolve the channel for a customer-scoped operation. Called with no
+     * argument it returns the bound channel (the member reads / redeem path). Called
+     * with a `channel` (e.g. the target of `linkChannel`) it validates that value
+     * against the `channels` allowlist and returns it — throwing pre-network on an
+     * out-of-vocabulary channel. Kept internal: resource groups consume it; it is not
+     * part of the documented public surface.
+     */
+    resolveChannel(channel?: string): string;
+}
+
+/**
+ * The SDK error taxonomy. One structured base class (`TesseraError`) carrying the
+ * stable, code-first envelope shape (`apps/api/src/errors.ts`), plus a typed subclass
+ * per stable wire `code` so a consumer can `catch` by TYPE — not by string-matching a
+ * `code` — and read `err.requestId` for support without ever parsing an HTTP body.
+ *
+ * The class identity comes from the snake_case `code`; the HTTP `status` flows from the
+ * response (never hard-coded here). `CODE_TO_ERROR` maps each `code` to its subclass and
+ * `errorFromEnvelope` constructs the right one. An UNKNOWN code yields the base
+ * `TesseraError` (forward-compat: a new server code never crashes an old SDK), so the
+ * factory NEVER throws on an unrecognized code.
+ */
+interface TesseraErrorInit {
+    /** The stable, snake_case error `code` (from the API envelope, or an SDK-local code). */
+    code: string;
+    /** Human-readable detail. Never branch on this — branch on `code` / the error type. */
+    message: string;
+    /** The `X-Request-Id` correlating this failure, for support. Absent pre-network. */
+    requestId?: string;
+    /** The HTTP status, when the error came from a response. Absent for pre-network errors. */
+    status?: number;
+    /** Structured, code-specific detail from the envelope (e.g. a redemption shortfall). */
+    details?: unknown;
+}
+declare class TesseraError extends Error {
+    /** The stable, snake_case error `code`; the contract consumers branch on. */
+    readonly code: string;
+    /** The `X-Request-Id` of the failing request, when available. */
+    readonly requestId?: string;
+    /** The HTTP status, when this error originated from a response. */
+    readonly status?: number;
+    /** Structured, code-specific detail carried from the envelope `details`. */
+    readonly details?: unknown;
+    constructor(init: TesseraErrorInit);
+}
+/** `invalid_request` (400) — a malformed request body / query the API rejected at its boundary. */
+declare class ValidationError extends TesseraError {
+}
+/** `unauthorized` (401) — missing, unknown, or revoked API key. */
+declare class UnauthorizedError extends TesseraError {
+}
+/** `signature_invalid` (401) — an event body's HMAC signature is absent or did not verify. */
+declare class SignatureInvalidError extends TesseraError {
+}
+/** `replay_detected` (401) — an event timestamp is outside the skew window, or its nonce was reused. */
+declare class ReplayDetectedError extends TesseraError {
+}
+/** `forbidden` (403) — the authenticated key lacks authority for this operation. */
+declare class ForbiddenError extends TesseraError {
+}
+/** `tier_gated` (403) — the redemption option requires a higher tier than the customer holds. */
+declare class TierGatedError extends TesseraError {
+}
+/** `publishable_key_forbidden` (403) — a publishable key was used on a secret-key-only endpoint. */
+declare class PublishableKeyForbiddenError extends TesseraError {
+}
+/** `not_found` (404) — the requested resource does not exist within the caller's tenant. */
+declare class NotFoundError extends TesseraError {
+}
+/** `customer_not_found` (404) — no such customer in this tenant (no cross-tenant existence leak). */
+declare class CustomerNotFoundError extends TesseraError {
+}
+/** `redemption_not_found` (404) — no such redemption in this tenant. */
+declare class RedemptionNotFoundError extends TesseraError {
+}
+/** `conflict` (409) — a generic state conflict. */
+declare class ConflictError extends TesseraError {
+}
+/**
+ * `idempotency_key_conflict` / `idempotency_key_reuse` (409) — an idempotency key was reused with a
+ * DIFFERENT payload. Both wire codes (the events-endpoint-specific `..._conflict` and the
+ * platform-wide `..._reuse`) surface as this one type.
+ */
+declare class IdempotencyConflictError extends TesseraError {
+}
+/** `version_conflict` (409) — an optimistic-concurrency stale write; re-read and retry. */
+declare class VersionConflictError extends TesseraError {
+}
+/** `cap_reached` (409) — the redemption limit for this option has been reached. */
+declare class CapReachedError extends TesseraError {
+}
+/** `not_stackable` (409) — a non-stackable option conflicts with an existing active hold. */
+declare class NotStackableError extends TesseraError {
+}
+/** `hold_already_released` (409) — finalizing a redemption hold that is already released (terminal). */
+declare class HoldAlreadyReleasedError extends TesseraError {
+}
+/** `customer_erased` (410) — the customer's PII has been erased (GDPR); the profile is gone. */
+declare class CustomerErasedError extends TesseraError {
+}
+/** `payload_too_large` (413) — the request body exceeded the API's size limit. */
+declare class PayloadTooLargeError extends TesseraError {
+}
+/**
+ * `insufficient_balance` (422) — the customer's `available` was below the redemption cost, so no hold
+ * was placed. `shortfall` is how far `available` fell short (read from the envelope `details`).
+ */
+declare class InsufficientBalanceError extends TesseraError {
+    /** How far `available` fell short of the cost, from `details.shortfall`; `undefined` if absent. */
+    get shortfall(): number | undefined;
+}
+/** `option_not_eligible` (422) — the option exists but a non-tier/non-cap eligibility rule failed. */
+declare class OptionNotEligibleError extends TesseraError {
+}
+/** `invalid_payload` (422) — a well-formed event body that failed the purchase-event contract. */
+declare class InvalidPayloadError extends TesseraError {
+}
+/** `unsupported_event_type` (422) — an event type not supported in this phase. */
+declare class UnsupportedEventTypeError extends TesseraError {
+}
+/**
+ * `profile_validation_error` (422) — a semantic profile-field validation failure (email/birthday/
+ * locale). `field` names the offending field (read from the envelope `details`).
+ */
+declare class ProfileValidationError extends TesseraError {
+    /** The offending profile field, from `details.field`; `undefined` if absent. */
+    get field(): string | undefined;
+}
+/** `rate_limited` (429) — the tenant exceeded its rate limit; honor `Retry-After` and back off. */
+declare class RateLimitedError extends TesseraError {
+}
+/** `internal_error` (500) — an opaque server error. */
+declare class InternalError extends TesseraError {
+}
+/** `not_implemented` (501) — a valid-vocabulary option that is not implemented this phase. */
+declare class NotImplementedError extends TesseraError {
+}
+/** The shape of an error-envelope subclass constructor. */
+type TesseraErrorClass = new (init: TesseraErrorInit) => TesseraError;
+/**
+ * The authoritative map from the operations API's stable snake_case wire `code` to the SDK error
+ * subclass a consumer catches. Keyed by `code` (NOT status) — status flows from the response. The
+ * contract-test suite (§8) asserts this covers every `code` the API can emit, so the server cannot
+ * add a code the SDK silently downgrades to the base error.
+ */
+declare const CODE_TO_ERROR: Record<string, TesseraErrorClass>;
+/**
+ * Build the right `TesseraError` subclass from a non-2xx response. `body` is the tolerantly-parsed
+ * JSON body (any shape); `requestId` is the captured `X-Request-Id` header (preferred over the
+ * envelope's `request_id`). An unknown or missing `code` yields the base `TesseraError` — this
+ * NEVER throws, so a new server code cannot crash an old SDK.
+ */
+declare function errorFromEnvelope(status: number, body: unknown, requestId?: string): TesseraError;
+
+/**
+ * Client-side HMAC signer for inbound event ingestion (`POST /v1/events`).
+ *
+ * This is the exact mirror of the engine's verifier so a signed request is accepted byte-for-byte.
+ * Source of truth: `packages/engine/src/crypto.ts` — `signEventPayload` / `signedPayload` /
+ * `verifyEventSignature`. The scheme (do NOT change without changing the engine):
+ *
+ *   - **Algorithm:** HMAC-SHA256, keyed on the per-tenant *connector* `signingSecret`
+ *     (`whsec_...`) — the credential separate from the bearer API key.
+ *   - **Canonical message:** the literal string `` `${timestamp}.${rawBody}` `` — the unix-seconds
+ *     timestamp, a single `.` delimiter, then the RAW request body byte-for-byte as sent. The nonce
+ *     is deliberately NOT part of the signed payload (it is an independent replay-defense header).
+ *   - **Encoding:** lowercase hex, presented with the scheme prefix `v1=`
+ *     (`X-Loyalty-Signature: v1=<hex>`).
+ *   - **Timestamp:** unix SECONDS as a string (the engine does `Number(timestamp)` and checks skew
+ *     against `Date.now()/1000`).
+ *   - **Nonce:** a fresh, opaque per-attempt value carried in `X-Loyalty-Nonce`; a verbatim resend
+ *     of the same nonce is a replay server-side.
+ *
+ * Runtime-self-contained: uses only Web Crypto (`globalThis.crypto.subtle` + `randomUUID`) and
+ * `TextEncoder`, so it runs on Node 20+, edge/Workers, Deno, and Bun with zero runtime deps and no
+ * `@loyalty/*` import. UTF-8 encoding via `TextEncoder` matches Node's default string encoding in
+ * the engine's `createHmac(...).update(string)`, so multibyte bodies sign identically.
+ */
+/** The signature scheme version prefix — matches the engine's `SIGNATURE_VERSION`. */
+declare const SIGNATURE_SCHEME = "v1";
+/** Header carrying the `v1=<hex>` HMAC signature. */
+declare const SIGNATURE_HEADER = "X-Loyalty-Signature";
+/** Header carrying the unix-seconds timestamp that is part of the signed payload. */
+declare const TIMESTAMP_HEADER = "X-Loyalty-Timestamp";
+/** Header carrying the per-attempt replay nonce (not signed). */
+declare const NONCE_HEADER = "X-Loyalty-Nonce";
+interface SignEventOptions {
+    /**
+     * The unix-SECONDS timestamp to sign with. A number is stringified; a string is used verbatim.
+     * Defaults to `Math.floor(now() / 1000)`. Injectable so tests are deterministic.
+     */
+    timestamp?: string | number;
+    /** The replay nonce. Defaults to `crypto.randomUUID()`. Injectable for deterministic tests. */
+    nonce?: string;
+    /** Millisecond clock used only to derive a default `timestamp`. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** The three signing headers, ready to spread into a request's `headers`. */
+interface SignedEventHeaders {
+    'X-Loyalty-Signature': string;
+    'X-Loyalty-Timestamp': string;
+    'X-Loyalty-Nonce': string;
+}
+interface SignedEvent {
+    /** `v1=<hex>` — the HMAC-SHA256 of `${timestamp}.${rawBody}` under the signing secret. */
+    signature: string;
+    /** The unix-seconds timestamp that was signed (echoed as `X-Loyalty-Timestamp`). */
+    timestamp: string;
+    /** The replay nonce (echoed as `X-Loyalty-Nonce`). */
+    nonce: string;
+    /** The complete set of signing headers to attach to the `POST /v1/events` request. */
+    headers: SignedEventHeaders;
+}
+/**
+ * Sign a raw event body for `POST /v1/events`.
+ *
+ * @param rawBody The exact request body string that will be sent — sign and send the SAME bytes;
+ *   re-serializing after signing invalidates the signature.
+ * @param signingSecret The per-tenant connector signing secret (`whsec_...`).
+ * @param opts Injectable `timestamp` / `nonce` / `now` (defaults: unix-seconds now, a random UUID).
+ * @returns The `v1=<hex>` signature plus the timestamp, nonce, and the ready-to-attach headers.
+ */
+declare function signEventBody(rawBody: string, signingSecret: string, opts?: SignEventOptions): Promise<SignedEvent>;
+
+/**
+ * `@tesseraloyalty/sdk` — the official TypeScript SDK for the Tessera loyalty platform's
+ * public operations API (`/v1`).
+ *
+ * This entry point exports the client, the error taxonomy, the public config types, the READ
+ * resources (the rewards catalogue + the `member(externalId)` handle), the `customers` identity/PII
+ * resource, the `redemptions` burn-hold lifecycle (`place`/`get`/`finalize`/`release` +
+ * `member.redeem`), the `events` signed-ingestion resource (`ingest` → `POST /v1/events`), and the
+ * `signEventBody` HMAC signer.
+ *
+ * Runtime-self-contained: it uses only global Web standards (`fetch` + friends), so
+ * it runs on Node 20+, edge/Workers, Deno, and Bun with zero runtime dependencies.
+ */
+
+/** The published version of this SDK. Kept in sync with `package.json` at release. */
+declare const VERSION = "0.1.0";
+/** The major version of the Tessera operations API this SDK targets. */
+declare const API_VERSION = "v1";
+
+export { API_VERSION, CODE_TO_ERROR, CapReachedError, ConflictError, type ConsentState, CustomerErasedError, CustomerNotFoundError, type CustomerPii, type CustomerProfileFields, type CustomerUpsertInput, type CustomerUpsertOptions, type CustomerUpsertResult, CustomersResource, type EventAmount, type EventType, EventsResource, type FetchLike, type FinalizeRedemptionInput, type FinalizeRedemptionResult, ForbiddenError, type HistoryEntry, type HistoryOptions, type HistoryPage, type HistoryPageInfo, HistoryPager, HoldAlreadyReleasedError, IdempotencyConflictError, type IngestEventInput, type IngestEventOptions, type IngestEventResult, InsufficientBalanceError, InternalError, InvalidPayloadError, type KeyType, type LinkChannelInput, type LinkChannelResult, type MarketingConsent, type MemberBalance, MemberHandle, type MemberOptions, type MemberProfile, type MemberRedeemInput, type MemberStatus, type MemberTier, NONCE_HEADER, NotFoundError, NotImplementedError, NotStackableError, OptionNotEligibleError, PayloadTooLargeError, type PlaceRedemptionInput, type PlaceRedemptionOptions, ProfileValidationError, PublishableKeyForbiddenError, type QualifyingProgress, RateLimitedError, type RedemptionHandle, RedemptionNotFoundError, type RedemptionResult, type RedemptionStatus, RedemptionsResource, type ReleaseRedemptionResult, ReplayDetectedError, type RewardOption, type RewardOptionConstraints, type RewardsCatalogue, RewardsResource, SIGNATURE_HEADER, SIGNATURE_SCHEME, type SignEventOptions, SignatureInvalidError, type SignedEvent, type SignedEventHeaders, TIMESTAMP_HEADER, TesseraClient, type TesseraClientConfig, TesseraError, type TesseraErrorInit, TierGatedError, UnauthorizedError, type UnlinkChannelResult, UnsupportedEventTypeError, VERSION, ValidationError, VersionConflictError, errorFromEnvelope, signEventBody };