@tesseraloyalty/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1210 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  API_VERSION: () => API_VERSION,
+  CODE_TO_ERROR: () => CODE_TO_ERROR,
+  CapReachedError: () => CapReachedError,
+  ConflictError: () => ConflictError,
+  CustomerErasedError: () => CustomerErasedError,
+  CustomerNotFoundError: () => CustomerNotFoundError,
+  CustomersResource: () => CustomersResource,
+  EventsResource: () => EventsResource,
+  ForbiddenError: () => ForbiddenError,
+  HistoryPager: () => HistoryPager,
+  HoldAlreadyReleasedError: () => HoldAlreadyReleasedError,
+  IdempotencyConflictError: () => IdempotencyConflictError,
+  InsufficientBalanceError: () => InsufficientBalanceError,
+  InternalError: () => InternalError,
+  InvalidPayloadError: () => InvalidPayloadError,
+  MemberHandle: () => MemberHandle,
+  NONCE_HEADER: () => NONCE_HEADER,
+  NotFoundError: () => NotFoundError,
+  NotImplementedError: () => NotImplementedError,
+  NotStackableError: () => NotStackableError,
+  OptionNotEligibleError: () => OptionNotEligibleError,
+  PayloadTooLargeError: () => PayloadTooLargeError,
+  ProfileValidationError: () => ProfileValidationError,
+  PublishableKeyForbiddenError: () => PublishableKeyForbiddenError,
+  RateLimitedError: () => RateLimitedError,
+  RedemptionNotFoundError: () => RedemptionNotFoundError,
+  RedemptionsResource: () => RedemptionsResource,
+  ReplayDetectedError: () => ReplayDetectedError,
+  RewardsResource: () => RewardsResource,
+  SIGNATURE_HEADER: () => SIGNATURE_HEADER,
+  SIGNATURE_SCHEME: () => SIGNATURE_SCHEME,
+  SignatureInvalidError: () => SignatureInvalidError,
+  TIMESTAMP_HEADER: () => TIMESTAMP_HEADER,
+  TesseraClient: () => TesseraClient,
+  TesseraError: () => TesseraError,
+  TierGatedError: () => TierGatedError,
+  UnauthorizedError: () => UnauthorizedError,
+  UnsupportedEventTypeError: () => UnsupportedEventTypeError,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
+  VersionConflictError: () => VersionConflictError,
+  errorFromEnvelope: () => errorFromEnvelope,
+  signEventBody: () => signEventBody
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var TesseraError = class extends Error {
+  /** The stable, snake_case error `code`; the contract consumers branch on. */
+  code;
+  /** The `X-Request-Id` of the failing request, when available. */
+  requestId;
+  /** The HTTP status, when this error originated from a response. */
+  status;
+  /** Structured, code-specific detail carried from the envelope `details`. */
+  details;
+  constructor(init) {
+    super(init.message);
+    this.name = new.target.name;
+    this.code = init.code;
+    this.requestId = init.requestId;
+    this.status = init.status;
+    this.details = init.details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function detailValue(details, key) {
+  if (details && typeof details === "object" && key in details) {
+    return details[key];
+  }
+  return void 0;
+}
+var ValidationError = class extends TesseraError {
+};
+var UnauthorizedError = class extends TesseraError {
+};
+var SignatureInvalidError = class extends TesseraError {
+};
+var ReplayDetectedError = class extends TesseraError {
+};
+var ForbiddenError = class extends TesseraError {
+};
+var TierGatedError = class extends TesseraError {
+};
+var PublishableKeyForbiddenError = class extends TesseraError {
+};
+var NotFoundError = class extends TesseraError {
+};
+var CustomerNotFoundError = class extends TesseraError {
+};
+var RedemptionNotFoundError = class extends TesseraError {
+};
+var ConflictError = class extends TesseraError {
+};
+var IdempotencyConflictError = class extends TesseraError {
+};
+var VersionConflictError = class extends TesseraError {
+};
+var CapReachedError = class extends TesseraError {
+};
+var NotStackableError = class extends TesseraError {
+};
+var HoldAlreadyReleasedError = class extends TesseraError {
+};
+var CustomerErasedError = class extends TesseraError {
+};
+var PayloadTooLargeError = class extends TesseraError {
+};
+var InsufficientBalanceError = class extends TesseraError {
+  /** How far `available` fell short of the cost, from `details.shortfall`; `undefined` if absent. */
+  get shortfall() {
+    const value = detailValue(this.details, "shortfall");
+    return typeof value === "number" ? value : void 0;
+  }
+};
+var OptionNotEligibleError = class extends TesseraError {
+};
+var InvalidPayloadError = class extends TesseraError {
+};
+var UnsupportedEventTypeError = class extends TesseraError {
+};
+var ProfileValidationError = class extends TesseraError {
+  /** The offending profile field, from `details.field`; `undefined` if absent. */
+  get field() {
+    const value = detailValue(this.details, "field");
+    return typeof value === "string" ? value : void 0;
+  }
+};
+var RateLimitedError = class extends TesseraError {
+};
+var InternalError = class extends TesseraError {
+};
+var NotImplementedError = class extends TesseraError {
+};
+var CODE_TO_ERROR = {
+  // 400
+  invalid_request: ValidationError,
+  // 401
+  unauthorized: UnauthorizedError,
+  signature_invalid: SignatureInvalidError,
+  replay_detected: ReplayDetectedError,
+  // 403
+  forbidden: ForbiddenError,
+  tier_gated: TierGatedError,
+  publishable_key_forbidden: PublishableKeyForbiddenError,
+  // 404
+  not_found: NotFoundError,
+  customer_not_found: CustomerNotFoundError,
+  redemption_not_found: RedemptionNotFoundError,
+  // 409
+  conflict: ConflictError,
+  idempotency_key_conflict: IdempotencyConflictError,
+  idempotency_key_reuse: IdempotencyConflictError,
+  version_conflict: VersionConflictError,
+  cap_reached: CapReachedError,
+  not_stackable: NotStackableError,
+  hold_already_released: HoldAlreadyReleasedError,
+  // 410
+  customer_erased: CustomerErasedError,
+  // 413
+  payload_too_large: PayloadTooLargeError,
+  // 422
+  insufficient_balance: InsufficientBalanceError,
+  option_not_eligible: OptionNotEligibleError,
+  invalid_payload: InvalidPayloadError,
+  unsupported_event_type: UnsupportedEventTypeError,
+  profile_validation_error: ProfileValidationError,
+  // 429
+  rate_limited: RateLimitedError,
+  // 500 / 501
+  internal_error: InternalError,
+  not_implemented: NotImplementedError
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function extractEnvelope(body) {
+  if (!isRecord(body)) return {};
+  const error = isRecord(body.error) ? body.error : void 0;
+  if (!error) return {};
+  return {
+    code: typeof error.code === "string" ? error.code : void 0,
+    message: typeof error.message === "string" ? error.message : void 0,
+    requestId: typeof error.request_id === "string" ? error.request_id : void 0,
+    details: error.details
+  };
+}
+function errorFromEnvelope(status, body, requestId) {
+  const env = extractEnvelope(body);
+  const code = env.code ?? "unknown_error";
+  const init = {
+    code,
+    message: env.message ?? `Request failed with HTTP ${status}.`,
+    status,
+    requestId: requestId ?? env.requestId,
+    details: env.details
+  };
+  const ErrorClass = CODE_TO_ERROR[code];
+  return ErrorClass ? new ErrorClass(init) : new TesseraError(init);
+}
+
+// src/http.ts
+var TimeoutSignal = class extends Error {
+};
+var HttpCore = class {
+  baseUrl;
+  token;
+  timeoutMs;
+  maxRetries;
+  fetchImpl;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.token = config.token;
+    this.timeoutMs = config.timeoutMs;
+    this.maxRetries = config.maxRetries;
+    this.fetchImpl = config.fetchImpl;
+  }
+  /**
+   * 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).
+   */
+  async request(method, path, opts = {}) {
+    const url = this.buildUrl(path, opts.query);
+    const hasRawBody = opts.rawBody !== void 0;
+    const hasBody = hasRawBody || opts.body !== void 0;
+    const headers = this.buildHeaders(opts, hasBody);
+    const body = hasRawBody ? opts.rawBody : opts.body !== void 0 ? JSON.stringify(opts.body) : void 0;
+    let attempt = 0;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.dispatch(method, url, headers, body);
+      } catch (err) {
+        if (err instanceof TimeoutSignal) {
+          throw new TesseraError({
+            code: "timeout",
+            message: `Request to ${method} ${path} timed out after ${this.timeoutMs}ms.`
+          });
+        }
+        if (attempt < this.maxRetries) {
+          await delay(backoffMs(attempt));
+          attempt += 1;
+          continue;
+        }
+        throw new TesseraError({
+          code: "network_error",
+          message: err instanceof Error ? err.message : "Network request failed.",
+          details: err
+        });
+      }
+      if (isRetriableStatus(response.status) && attempt < this.maxRetries) {
+        const retryAfterMs = parseRetryAfter(response.headers.get("Retry-After"));
+        await delay(retryAfterMs ?? backoffMs(attempt));
+        attempt += 1;
+        continue;
+      }
+      const requestId = response.headers.get("X-Request-Id") ?? void 0;
+      if (response.status >= 200 && response.status < 300) {
+        return await readJson(response);
+      }
+      const errorBody = await readJson(response);
+      throw errorFromEnvelope(response.status, errorBody, requestId);
+    }
+  }
+  /** One fetch attempt, raced against a per-attempt timeout that aborts the request. */
+  async dispatch(method, url, headers, body) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new TimeoutSignal());
+      }, this.timeoutMs);
+    });
+    try {
+      return await Promise.race([
+        this.fetchImpl(url, { method, headers, body, signal: controller.signal }),
+        timeout
+      ]);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+  buildUrl(path, query) {
+    const rel = path.startsWith("/") ? path : `/${path}`;
+    let url = `${this.baseUrl}${rel}`;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== null) params.set(key, String(value));
+      }
+      const qs = params.toString();
+      if (qs) url += `?${qs}`;
+    }
+    return url;
+  }
+  buildHeaders(opts, hasBody) {
+    const headers = new Headers(opts.headers);
+    headers.set("Authorization", `Bearer ${this.token}`);
+    headers.set("Accept", "application/json");
+    if (hasBody) headers.set("Content-Type", "application/json");
+    if (opts.idempotencyKey) headers.set("Idempotency-Key", opts.idempotencyKey);
+    return headers;
+  }
+};
+function isRetriableStatus(status) {
+  return status === 429 || status >= 500;
+}
+function backoffMs(attempt) {
+  const base = 200;
+  const cap = 2e4;
+  return Math.min(cap, base * 2 ** attempt);
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const at = Date.parse(value);
+  if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
+  return void 0;
+}
+async function readJson(response) {
+  let text;
+  try {
+    text = await response.text();
+  } catch {
+    return void 0;
+  }
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/internal/camel.ts
+function snakeToCamel(key) {
+  return key.replace(/[_-]+([a-z0-9])/g, (_match, ch) => ch.toUpperCase());
+}
+function deepCamelize(value) {
+  if (Array.isArray(value)) return value.map(deepCamelize);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[snakeToCamel(key)] = deepCamelize(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/resources/rewards.ts
+function toRewardOption(w) {
+  const c = w.constraints;
+  return {
+    id: w.id,
+    type: w.type,
+    label: w.label,
+    mechanism: w.mechanism,
+    triggerSurfaces: w.trigger_surfaces,
+    // The cost model is an open variant record — deep-camelCase its keys generically.
+    costModel: deepCamelize(w.cost_model),
+    costPoints: w.cost_points,
+    constraints: {
+      minSpendCents: c.min_spend_cents,
+      eligibleCollectionIds: c.eligible_collection_ids,
+      eligibleProductIds: c.eligible_product_ids,
+      stackable: c.stackable,
+      perCustomerCap: c.per_customer_cap ? { count: c.per_customer_cap.count, window: c.per_customer_cap.window } : null,
+      tierGate: c.tier_gate,
+      valueCapCents: c.value_cap_cents
+    }
+  };
+}
+var RewardsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Fetch the public rewards catalogue. `keyScope: 'publishable'` — allowed with a publishable OR
+   * a secret key (the one read a browser/publishable client may perform).
+   */
+  async list() {
+    const wire = await this.http.request("GET", "/rewards", {
+      keyScope: "publishable"
+    });
+    return {
+      pointsLabel: wire.points_label,
+      data: (wire.data ?? []).map(toRewardOption)
+    };
+  }
+};
+
+// src/internal/scope.ts
+function assertSecretKey(keyType, message) {
+  if (keyType === "secret") return;
+  throw new PublishableKeyForbiddenError({ code: "publishable_key_forbidden", message });
+}
+
+// src/internal/serialize.ts
+function toIso(value) {
+  if (value === void 0) return void 0;
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+// src/resources/members.ts
+function toProfile(w) {
+  return {
+    customerUuid: w.customer_uuid,
+    channel: w.channel,
+    externalId: w.external_id,
+    createdAt: w.created_at
+  };
+}
+function toBalance(w) {
+  return {
+    customerUuid: w.customer_uuid,
+    pointsLabel: w.points_label,
+    spendableBalance: w.spendable_balance,
+    pendingSpendable: w.pending_spendable,
+    qualifyingBalance: w.qualifying_balance,
+    activeHolds: w.active_holds,
+    clawbacksOutstanding: w.clawbacks_outstanding,
+    available: w.available
+  };
+}
+function toStatus(w) {
+  const p = w.qualifying_progress;
+  return {
+    customerUuid: w.customer_uuid,
+    currentTier: w.current_tier ? {
+      key: w.current_tier.key,
+      name: w.current_tier.name,
+      earnMultiplier: w.current_tier.earn_multiplier,
+      rewardEligibility: w.current_tier.reward_eligibility
+    } : null,
+    effectiveTierKey: w.effective_tier_key,
+    periodStart: w.period_start,
+    periodEnd: w.period_end,
+    requalificationState: w.requalification_state,
+    graceDeadline: w.grace_deadline,
+    qualifyingProgress: {
+      current: p.current,
+      holdThreshold: p.hold_threshold,
+      nextTierKey: p.next_tier_key,
+      nextQualifyThreshold: p.next_qualify_threshold
+    }
+  };
+}
+function toHistoryEntry(w) {
+  return {
+    id: w.id,
+    type: w.type,
+    currency: w.currency,
+    amount: w.amount,
+    state: w.state,
+    sourceChannel: w.source_channel,
+    sourceRef: w.source_ref,
+    sourceEventId: w.source_event_id,
+    createdAt: w.created_at
+  };
+}
+var HistoryPager = class {
+  constructor(fetchPage) {
+    this.fetchPage = fetchPage;
+  }
+  fetchPage;
+  async *[Symbol.asyncIterator]() {
+    let cursor;
+    for (; ; ) {
+      const page = await this.fetchPage(cursor);
+      for (const entry of page.data) yield entry;
+      const next = page.page.nextCursor;
+      if (!page.page.hasMore || next === null || next === void 0) return;
+      cursor = next;
+    }
+  }
+  then(onfulfilled, onrejected) {
+    return this.fetchPage(void 0).then(onfulfilled, onrejected);
+  }
+};
+var MemberHandle = class {
+  /** The channel bound to this handle (from the client's `resolveChannel()`). */
+  channel;
+  /** The merchant-facing external id this handle reads. */
+  externalId;
+  http;
+  keyType;
+  redemptions;
+  constructor(deps) {
+    this.http = deps.http;
+    this.keyType = deps.keyType;
+    this.channel = deps.channel;
+    this.externalId = deps.externalId;
+    this.redemptions = deps.redemptions;
+  }
+  /** The `/customers/:channel/:externalId` path prefix (both segments URL-encoded). */
+  base() {
+    return `/customers/${encodeURIComponent(this.channel)}/${encodeURIComponent(this.externalId)}`;
+  }
+  /** Fail fast pre-network when a secret-scope read is attempted with a publishable key. */
+  requireSecret() {
+    assertSecretKey(
+      this.keyType,
+      "This member read requires a secret key. The client is configured with a publishable key (catalogue-only). Construct the client with `secretKey` to read a member."
+    );
+  }
+  /** The pseudonymous member profile (identity + channel binding; no PII). */
+  async get() {
+    this.requireSecret();
+    const wire = await this.http.request("GET", this.base(), {
+      keyScope: "secret"
+    });
+    return toProfile(wire);
+  }
+  /** The member's balances (spendable / pending / qualifying / holds / available). */
+  async balance() {
+    this.requireSecret();
+    const wire = await this.http.request("GET", `${this.base()}/balance`, {
+      keyScope: "secret"
+    });
+    return toBalance(wire);
+  }
+  /** The member's tier status + progress toward the next tier. */
+  async status() {
+    this.requireSecret();
+    const wire = await this.http.request("GET", `${this.base()}/status`, {
+      keyScope: "secret"
+    });
+    return toStatus(wire);
+  }
+  /**
+   * 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 = {}) {
+    this.requireSecret();
+    const baseQuery = {
+      limit: opts.limit,
+      type: opts.types && opts.types.length > 0 ? opts.types.join(",") : void 0,
+      since: toIso(opts.since),
+      until: toIso(opts.until)
+    };
+    const fetchPage = async (cursor) => {
+      const wire = await this.http.request("GET", `${this.base()}/history`, {
+        keyScope: "secret",
+        query: { ...baseQuery, cursor: cursor ?? opts.cursor }
+      });
+      return {
+        data: (wire.data ?? []).map(toHistoryEntry),
+        page: {
+          nextCursor: wire.page?.next_cursor ?? null,
+          hasMore: wire.page?.has_more ?? false
+        }
+      };
+    };
+    return new HistoryPager(fetchPage);
+  }
+  /**
+   * 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.
+   */
+  async redeem(input, opts) {
+    const result = await this.redemptions.place(
+      {
+        optionId: input.optionId,
+        externalId: this.externalId,
+        channel: this.channel,
+        cartSubtotalCents: input.cartSubtotalCents,
+        requestedValueCents: input.requestedValueCents,
+        expiresAt: input.expiresAt
+      },
+      opts
+    );
+    return this.redemptions.toHandle(result);
+  }
+};
+
+// src/resources/customers.ts
+function marketingConsentToWire(mc) {
+  const out = {};
+  if (mc.email !== void 0) out.email = mc.email;
+  if (mc.sms !== void 0) out.sms = mc.sms;
+  if (mc.updatedAt !== void 0) out.updated_at = mc.updatedAt;
+  return out;
+}
+function profileFieldsToWire(fields) {
+  const out = {};
+  if (fields.email !== void 0) out.email = fields.email;
+  if (fields.name !== void 0) out.name = fields.name;
+  if (fields.birthday !== void 0) out.birthday = fields.birthday;
+  if (fields.locale !== void 0) out.locale = fields.locale;
+  if (fields.socialHandles !== void 0) out.social_handles = fields.socialHandles;
+  if (fields.marketingConsent !== void 0) {
+    out.marketing_consent = fields.marketingConsent === null ? null : marketingConsentToWire(fields.marketingConsent);
+  }
+  return out;
+}
+function toPii(w) {
+  const out = { customerUuid: w.customer_uuid };
+  if (w.email !== void 0) out.email = w.email;
+  if (w.name !== void 0) out.name = w.name;
+  if (w.birthday !== void 0) out.birthday = w.birthday;
+  if (w.locale !== void 0) out.locale = w.locale;
+  if (w.social_handles !== void 0) out.socialHandles = w.social_handles;
+  if (w.marketing_consent !== void 0) {
+    const mc = w.marketing_consent;
+    const consent = {};
+    if (mc.email !== void 0) consent.email = mc.email;
+    if (mc.sms !== void 0) consent.sms = mc.sms;
+    if (mc.updated_at !== void 0) consent.updatedAt = mc.updated_at;
+    out.marketingConsent = consent;
+  }
+  if (w.updated_at !== void 0) out.updatedAt = w.updated_at;
+  return out;
+}
+var CustomersResource = class {
+  http;
+  keyType;
+  resolveChannel;
+  constructor(deps) {
+    this.http = deps.http;
+    this.keyType = deps.keyType;
+    this.resolveChannel = deps.resolveChannel;
+  }
+  /** Fail fast pre-network when a secret-scope write is attempted with a publishable key. */
+  requireSecret() {
+    assertSecretKey(
+      this.keyType,
+      "This customer operation requires a secret key. The client is configured with a publishable key (catalogue-only). Construct the client with `secretKey`."
+    );
+  }
+  /**
+   * 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, opts = {}) {
+    const channel = this.resolveChannel(input.channel);
+    return this.sendUpsert(channel, input, opts);
+  }
+  async sendUpsert(channel, input, opts) {
+    this.requireSecret();
+    const body = {
+      external_id: input.externalId,
+      channel,
+      ...profileFieldsToWire(input)
+    };
+    const wire = await this.http.request("POST", "/customers", {
+      keyScope: "secret",
+      body,
+      idempotencyKey: opts.idempotencyKey
+    });
+    return {
+      customerUuid: wire.customer_uuid,
+      channel: wire.channel,
+      externalId: wire.external_id,
+      created: wire.created,
+      updatedAt: wire.updated_at
+    };
+  }
+  /**
+   * 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`.
+   */
+  async update(ref, fields) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "PATCH",
+      `/customers/${encodeURIComponent(ref)}`,
+      { keyScope: "secret", body: profileFieldsToWire(fields) }
+    );
+    return toPii(wire);
+  }
+  /**
+   * Read a customer's decrypted PII by UUID (`GET /v1/customers/:uuid`). Secret-only. 404 →
+   * `CustomerNotFoundError` (no cross-tenant existence leak).
+   */
+  async getPii(uuid) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "GET",
+      `/customers/${encodeURIComponent(uuid)}`,
+      { keyScope: "secret" }
+    );
+    return toPii(wire);
+  }
+  /**
+   * 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, input) {
+    const channel = this.resolveChannel(input.channel);
+    return this.sendLink(uuid, channel, input.externalId);
+  }
+  async sendLink(uuid, channel, externalId) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "POST",
+      `/customers/${encodeURIComponent(uuid)}/links`,
+      { keyScope: "secret", body: { channel, external_id: externalId } }
+    );
+    return {
+      customerUuid: wire.customer_uuid,
+      linkedVia: wire.linked_via,
+      status: wire.status
+    };
+  }
+  /**
+   * 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.
+   */
+  async unlinkChannel(uuid, channel, externalId) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "DELETE",
+      `/customers/${encodeURIComponent(uuid)}/links/${encodeURIComponent(channel)}/${encodeURIComponent(externalId)}`,
+      { keyScope: "secret" }
+    );
+    return { status: wire.status };
+  }
+};
+
+// src/resources/redemptions.ts
+function toRedemptionResult(w) {
+  return {
+    redemptionId: w.redemption_id,
+    customerUuid: w.customer_uuid,
+    optionId: w.option_id,
+    amount: w.amount,
+    discountValueCents: w.discount_value_cents,
+    mechanism: w.mechanism,
+    state: w.state,
+    expiresAt: w.expires_at ?? null,
+    createdAt: w.created_at
+  };
+}
+var RedemptionsResource = class {
+  http;
+  keyType;
+  resolveChannel;
+  constructor(deps) {
+    this.http = deps.http;
+    this.keyType = deps.keyType;
+    this.resolveChannel = deps.resolveChannel;
+  }
+  /** Fail fast pre-network when a secret-scope operation is attempted with a publishable key. */
+  requireSecret() {
+    assertSecretKey(
+      this.keyType,
+      "This redemption operation requires a secret key. The client is configured with a publishable key (catalogue-only). Construct the client with `secretKey`."
+    );
+  }
+  /**
+   * 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, opts = {}) {
+    const channel = this.resolveChannel(input.channel);
+    return this.sendPlace(channel, input, opts);
+  }
+  async sendPlace(channel, input, opts) {
+    this.requireSecret();
+    const body = {
+      option_id: input.optionId,
+      customer_channel: channel,
+      customer_external_id: input.externalId
+    };
+    if (input.cartSubtotalCents !== void 0) body.cart_subtotal_cents = input.cartSubtotalCents;
+    if (input.requestedValueCents !== void 0)
+      body.requested_value_cents = input.requestedValueCents;
+    if (input.expiresAt !== void 0) body.expires_at = toIso(input.expiresAt);
+    const idempotencyKey = opts.idempotencyKey ?? crypto.randomUUID();
+    const wire = await this.http.request("POST", "/redemptions", {
+      keyScope: "secret",
+      body,
+      idempotencyKey
+    });
+    return toRedemptionResult(wire);
+  }
+  /**
+   * Read a redemption hold's status (`GET /v1/redemptions/:id`). Tenant-scoped: 404 →
+   * {@link RedemptionNotFoundError} (no cross-tenant existence leak).
+   */
+  async get(id) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "GET",
+      `/redemptions/${encodeURIComponent(id)}`,
+      { keyScope: "secret" }
+    );
+    return { redemptionId: wire.redemption_id, state: wire.state, amount: wire.amount };
+  }
+  /**
+   * 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.
+   */
+  async finalize(id, input) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "POST",
+      `/redemptions/${encodeURIComponent(id)}/finalize`,
+      {
+        keyScope: "secret",
+        body: { source_channel: input.sourceChannel, source_ref: input.sourceRef }
+      }
+    );
+    return { redemptionId: wire.redemption_id, state: "finalized" };
+  }
+  /**
+   * Release a hold — abandon it and restore the reserved points (`POST /v1/redemptions/:id/release`).
+   * Idempotent. Returns the member's `available` after the restore.
+   */
+  async release(id) {
+    this.requireSecret();
+    const wire = await this.http.request(
+      "POST",
+      `/redemptions/${encodeURIComponent(id)}/release`,
+      { keyScope: "secret" }
+    );
+    return { redemptionId: wire.redemption_id, state: "released", available: wire.available };
+  }
+  /**
+   * @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) {
+    return {
+      ...result,
+      finalize: (input) => this.finalize(result.redemptionId, input),
+      release: () => this.release(result.redemptionId)
+    };
+  }
+};
+
+// src/signing.ts
+var SIGNATURE_SCHEME = "v1";
+var SIGNATURE_HEADER = "X-Loyalty-Signature";
+var TIMESTAMP_HEADER = "X-Loyalty-Timestamp";
+var NONCE_HEADER = "X-Loyalty-Nonce";
+function canonicalMessage(timestamp, rawBody) {
+  return `${timestamp}.${rawBody}`;
+}
+function webCrypto() {
+  const c = globalThis.crypto;
+  if (!c || !c.subtle) {
+    throw new Error(
+      "Web Crypto (globalThis.crypto.subtle) is unavailable in this runtime; @tesseraloyalty/sdk event signing requires Node 20+, an edge/Workers runtime, Deno, or Bun."
+    );
+  }
+  return c;
+}
+function toHex(bytes) {
+  const view = new Uint8Array(bytes);
+  let out = "";
+  for (let i = 0; i < view.length; i += 1) {
+    out += view[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+async function hmacSha256Hex(secret, message) {
+  const encoder = new TextEncoder();
+  const key = await webCrypto().subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await webCrypto().subtle.sign("HMAC", key, encoder.encode(message));
+  return toHex(signature);
+}
+async function signEventBody(rawBody, signingSecret, opts = {}) {
+  const nowMs = opts.now ? opts.now() : Date.now();
+  const timestamp = opts.timestamp !== void 0 ? String(opts.timestamp) : String(Math.floor(nowMs / 1e3));
+  const nonce = opts.nonce ?? webCrypto().randomUUID();
+  const hex = await hmacSha256Hex(signingSecret, canonicalMessage(timestamp, rawBody));
+  const signature = `${SIGNATURE_SCHEME}=${hex}`;
+  return {
+    signature,
+    timestamp,
+    nonce,
+    headers: {
+      "X-Loyalty-Signature": signature,
+      "X-Loyalty-Timestamp": timestamp,
+      "X-Loyalty-Nonce": nonce
+    }
+  };
+}
+
+// src/resources/events.ts
+var AMOUNT_KEY_MAP = {
+  gross: "gross",
+  netOfTaxShipping: "net_of_tax_shipping",
+  finalAfterDiscounts: "final_after_discounts",
+  currency: "currency",
+  refundedBase: "refunded_base",
+  orderBase: "order_base"
+};
+function amountToWire(amount) {
+  const out = {};
+  for (const [key, value] of Object.entries(amount)) {
+    if (value === void 0) continue;
+    out[AMOUNT_KEY_MAP[key] ?? key] = value;
+  }
+  return out;
+}
+function toWireBody(input) {
+  const wire = {
+    type: input.type,
+    channel: input.channel,
+    external_id: input.externalId,
+    source_ref: input.sourceRef,
+    idempotency_key: input.idempotencyKey,
+    occurred_at: toIso(input.occurredAt)
+  };
+  if (input.tenant !== void 0) wire.tenant = input.tenant;
+  if (input.trigger !== void 0) wire.trigger = input.trigger;
+  if (input.orderRef !== void 0) wire.order_ref = input.orderRef;
+  if (input.amount !== void 0) wire.amount = amountToWire(input.amount);
+  if (input.email !== void 0) wire.email = input.email;
+  if (input.phone !== void 0) wire.phone = input.phone;
+  return wire;
+}
+function toResult(w) {
+  return {
+    eventId: w.event_id,
+    customerId: w.customer_id,
+    channel: w.channel,
+    sourceRef: w.source_ref,
+    type: w.type,
+    status: w.status,
+    customerCreated: w.customer_created,
+    linkedVia: w.linked_via,
+    enqueued: w.enqueued
+  };
+}
+var EventsResource = class {
+  http;
+  keyType;
+  signingSecret;
+  constructor(deps) {
+    this.http = deps.http;
+    this.keyType = deps.keyType;
+    this.signingSecret = deps.signingSecret;
+  }
+  /** Fail fast pre-network when signed ingestion is attempted with a publishable key. */
+  requireSecret() {
+    assertSecretKey(
+      this.keyType,
+      "Event ingestion requires a secret key. The client is configured with a publishable key (catalogue-only). Construct the client with `secretKey`."
+    );
+  }
+  /**
+   * 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.
+   */
+  requireSigningSecret() {
+    if (this.signingSecret) return this.signingSecret;
+    throw new TesseraError({
+      code: "config_error",
+      message: "Event ingestion requires a `signingSecret` (the per-tenant connector HMAC secret, `whsec_...`) \u2014 it is separate from the API key. Construct the client with `signingSecret`."
+    });
+  }
+  /**
+   * 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).
+   */
+  async ingest(input, opts = {}) {
+    this.requireSecret();
+    const signingSecret = this.requireSigningSecret();
+    const rawBody = JSON.stringify(toWireBody(input));
+    const signed = await signEventBody(rawBody, signingSecret);
+    const wire = await this.http.request("POST", "/events", {
+      keyScope: "secret",
+      rawBody,
+      // Spread into a fresh object literal so the fixed-key `SignedEventHeaders` interface widens to
+      // the transport's `Record<string, string>` header bag.
+      headers: { ...signed.headers },
+      idempotencyKey: opts.idempotencyKey
+    });
+    return toResult(wire);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.usetessera.io/v1";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_CHANNEL = "api";
+var TesseraClient = class _TesseraClient {
+  /** Whether this client authenticates with a secret or publishable key. */
+  keyType;
+  /** The channel bound to customer-scoped operations (default `'api'`). */
+  channel;
+  /** The optional channel allowlist. When set, every channel used must be a member. */
+  channels;
+  /** The per-tenant events signing secret, if configured (used by TER-87). */
+  signingSecret;
+  /** The resolved `/v1` base URL. */
+  baseUrl;
+  /** The per-request timeout in milliseconds. */
+  timeoutMs;
+  /** The maximum retry count on retriable failures. */
+  maxRetries;
+  /**
+   * @internal The shared HTTP transport. Resource groups (later tickets) issue their
+   * requests through this; it is not part of the documented public surface.
+   */
+  http;
+  constructor(config) {
+    const hasSecret = nonEmpty(config.secretKey);
+    const hasPublishable = nonEmpty(config.publishableKey);
+    if (hasSecret === hasPublishable) {
+      throw new TesseraError({
+        code: "config_error",
+        message: hasSecret ? "Provide exactly one of `secretKey` or `publishableKey` \u2014 not both." : "A `secretKey` or `publishableKey` is required to construct a TesseraClient."
+      });
+    }
+    this.keyType = hasSecret ? "secret" : "publishable";
+    const token = hasSecret ? config.secretKey : config.publishableKey;
+    this.signingSecret = config.signingSecret;
+    this.channels = config.channels;
+    const channel = config.channel ?? DEFAULT_CHANNEL;
+    assertChannelAllowed(channel, this.channels);
+    this.channel = channel;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new TesseraError({
+        code: "config_error",
+        message: "No global `fetch` is available in this runtime. Pass a `fetch` implementation in the TesseraClient config."
+      });
+    }
+    this.http = new HttpCore({
+      baseUrl: this.baseUrl,
+      token,
+      timeoutMs: this.timeoutMs,
+      maxRetries: this.maxRetries,
+      fetchImpl
+    });
+  }
+  /**
+   * 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) {
+    assertChannelAllowed(channel, this.channels);
+    const scoped = Object.create(_TesseraClient.prototype);
+    scoped.keyType = this.keyType;
+    scoped.channel = channel;
+    scoped.channels = this.channels;
+    scoped.signingSecret = this.signingSecret;
+    scoped.baseUrl = this.baseUrl;
+    scoped.timeoutMs = this.timeoutMs;
+    scoped.maxRetries = this.maxRetries;
+    scoped.http = this.http;
+    return scoped;
+  }
+  /**
+   * 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() {
+    return new RewardsResource(this.http);
+  }
+  /**
+   * 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() {
+    return new CustomersResource({
+      http: this.http,
+      keyType: this.keyType,
+      resolveChannel: (channel) => this.resolveChannel(channel)
+    });
+  }
+  /**
+   * 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() {
+    return new RedemptionsResource({
+      http: this.http,
+      keyType: this.keyType,
+      resolveChannel: (channel) => this.resolveChannel(channel)
+    });
+  }
+  /**
+   * 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() {
+    return new EventsResource({
+      http: this.http,
+      keyType: this.keyType,
+      signingSecret: this.signingSecret
+    });
+  }
+  /**
+   * 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, opts) {
+    const channel = this.resolveChannel(opts?.channel);
+    return new MemberHandle({
+      http: this.http,
+      keyType: this.keyType,
+      channel,
+      externalId,
+      redemptions: this.redemptions
+    });
+  }
+  /**
+   * @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) {
+    if (channel === void 0) return this.channel;
+    assertChannelAllowed(channel, this.channels);
+    return channel;
+  }
+};
+function nonEmpty(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function assertChannelAllowed(channel, allowlist) {
+  if (!allowlist || allowlist.includes(channel)) return;
+  throw new TesseraError({
+    code: "config_error",
+    message: `Channel "${channel}" is not in this client's configured \`channels\` allowlist. Known channels: ${allowlist.join(", ")}.`
+  });
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var API_VERSION = "v1";
+//# sourceMappingURL=index.cjs.map