@usethrottle/discounts 0.1.0

package/CLAUDE.md

@@ -0,0 +1,27 @@
+# @usethrottle/discounts
+
+Headless public SDK for Throttle discount and promotion code APIs.
+
+## Scope
+
+- Server-side TypeScript client only. Do not add browser UI components here.
+- Keep support limited to `percentage` and `fixed_amount`.
+- Preserve `metadata` as an arbitrary JSON object on create/update/get/list.
+- `maxRedemptionsPerCustomer` defaults to `1`; `null` means unlimited.
+- Customer redemption usage is counted on cart-to-order creation, not preview.
+- Preview is non-mutating: `POST /api/v1/discounts/preview`.
+- Cart application is mutating and must remain server-side:
+  `POST /api/v1/carts/:cartId/apply-discount` and
+  `DELETE /api/v1/carts/:cartId/discount`.
+- Never encourage exposing `THROTTLE_API_KEY` to buyer browsers.
+
+## Testing
+
+Focused commands:
+
+- `pnpm --filter @usethrottle/discounts test`
+- `pnpm --filter @usethrottle/discounts typecheck`
+- `pnpm --filter @usethrottle/discounts build`
+
+When endpoint shapes change, update `README.md`, package types, tests, and
+`apps/docs` in the same change.

package/README.md

@@ -0,0 +1,84 @@
+# @usethrottle/discounts
+
+Headless TypeScript client for Throttle discount codes.
+
+Use it from your server, API routes, server actions, or backend jobs. The SDK
+does not ship checkout UI because promotion code fields need to match each
+storefront's cart and checkout experience.
+
+## Install
+
+```bash
+npm install @usethrottle/discounts
+```
+
+## Preview a Code
+
+```ts
+import { DiscountsClient } from '@usethrottle/discounts';
+
+const discounts = new DiscountsClient({
+  apiKey: process.env.THROTTLE_API_KEY!,
+});
+
+const preview = await discounts.preview({
+  code: 'SUMMER25',
+  currency: 'USD',
+  subtotal: 10000,
+  customerId: 'cust_123',
+});
+
+if (preview.valid) {
+  console.log(preview.discountTotal); // 2500
+}
+```
+
+## Apply a Code to a Cart
+
+```ts
+const cart = await discounts.applyToCart('cart_123', 'SUMMER25');
+```
+
+## Remove a Code from a Cart
+
+```ts
+const cart = await discounts.removeFromCart('cart_123');
+```
+
+## Create a Discount
+
+```ts
+await discounts.create({
+  code: 'SUMMER25',
+  name: 'Summer 25% off',
+  type: 'percentage',
+  value: 25,
+  conditions: { minOrder: 5000 },
+  maxRedemptionsPerCustomer: 1,
+  metadata: {
+    campaign: 'summer-2026',
+    channel: 'email',
+  },
+});
+
+await discounts.create({
+  code: 'FIVE-OFF',
+  name: '$5 off',
+  type: 'fixed_amount',
+  value: 500,
+});
+```
+
+Throttle supports only `percentage` and `fixed_amount` discounts. `value` is a
+whole percent for percentage discounts and minor currency units for fixed
+amount discounts.
+
+`maxRedemptionsPerCustomer` defaults to `1`. Set it to another integer for
+repeat customer use, or `null` for unlimited customer redemptions. Redemption
+usage is counted when a discounted cart becomes an order.
+
+## API Key Safety
+
+This package sends `X-API-Key` to the Throttle API. Use it from a trusted server
+environment only. Browser checkout UIs should call your own API route or server
+action, then your server can use this package.

package/dist/index.cjs

@@ -0,0 +1,163 @@
+"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, {
+  DiscountsClient: () => DiscountsClient,
+  ThrottleDiscountsError: () => ThrottleDiscountsError,
+  createDiscountsClient: () => createDiscountsClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ThrottleDiscountsError = class extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(args) {
+    super(args.message);
+    this.name = "ThrottleDiscountsError";
+    this.code = args.code;
+    this.statusCode = args.statusCode;
+    this.details = args.details;
+  }
+};
+
+// src/client.ts
+var DiscountsClient = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("DiscountsClient: apiKey is required");
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!fetchImpl) throw new Error("DiscountsClient: fetch is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(method, path, body) {
+    const envelope = await this.requestEnvelope(method, path, body);
+    return envelope.data;
+  }
+  async requestEnvelope(method, path, body) {
+    const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          "x-api-key": this.apiKey,
+          "content-type": "application/json"
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: ctrl.signal
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new ThrottleDiscountsError({
+          code: json?.error?.code ?? "unknown_error",
+          message: json?.error?.message ?? `HTTP ${res.status}`,
+          statusCode: res.status,
+          details: json?.error?.details
+        });
+      }
+      return {
+        data: json.data,
+        meta: json.meta
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  create(input) {
+    return this.request("POST", "/api/v1/discounts", serializeDates(input));
+  }
+  async list(params = {}) {
+    const query = new URLSearchParams();
+    if (params.storeId) query.set("storeId", params.storeId);
+    if (params.isActive !== void 0) query.set("isActive", String(params.isActive));
+    if (params.code) query.set("code", params.code);
+    if (params.limit !== void 0) query.set("limit", String(params.limit));
+    if (params.cursor) query.set("cursor", params.cursor);
+    if (params.sort) query.set("sort", params.sort);
+    const suffix = query.toString() ? `?${query}` : "";
+    const envelope = await this.requestEnvelope("GET", `/api/v1/discounts${suffix}`);
+    return {
+      data: envelope.data,
+      pagination: envelope.meta?.pagination ?? void 0
+    };
+  }
+  get(id) {
+    return this.request("GET", `/api/v1/discounts/${encodeURIComponent(id)}`);
+  }
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `/api/v1/discounts/${encodeURIComponent(id)}`,
+      serializeDates(input)
+    );
+  }
+  delete(id) {
+    return this.request("DELETE", `/api/v1/discounts/${encodeURIComponent(id)}`);
+  }
+  validate(code, orderTotal, customerId) {
+    return this.request("POST", "/api/v1/discounts/validate", {
+      code,
+      orderTotal,
+      ...customerId ? { customerId } : {}
+    });
+  }
+  preview(input) {
+    return this.request("POST", "/api/v1/discounts/preview", input);
+  }
+  applyToCart(cartId, code) {
+    return this.request(
+      "POST",
+      `/api/v1/carts/${encodeURIComponent(cartId)}/apply-discount`,
+      {
+        code
+      }
+    );
+  }
+  removeFromCart(cartId) {
+    return this.request("DELETE", `/api/v1/carts/${encodeURIComponent(cartId)}/discount`);
+  }
+};
+function createDiscountsClient(opts) {
+  return new DiscountsClient(opts);
+}
+function serializeDates(input) {
+  const out = { ...input };
+  for (const key of ["startsAt", "endsAt"]) {
+    const value = out[key];
+    if (value instanceof Date) out[key] = value.toISOString();
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DiscountsClient,
+  ThrottleDiscountsError,
+  createDiscountsClient
+});

package/dist/index.d.cts

@@ -0,0 +1,145 @@
+type DiscountType = 'percentage' | 'fixed_amount';
+interface Discount {
+    id: string;
+    code: string | null;
+    name: string;
+    type: DiscountType;
+    value: number;
+    conditions: Record<string, unknown>;
+    usageLimit?: number | null;
+    usageCount: number;
+    maxRedemptionsPerCustomer?: number | null;
+    isActive: boolean;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+interface CreateDiscountInput {
+    storeId?: string;
+    code?: string;
+    name: string;
+    type: DiscountType;
+    value: number;
+    conditions?: Record<string, unknown>;
+    usageLimit?: number;
+    maxRedemptionsPerCustomer?: number | null;
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateDiscountInput {
+    name?: string;
+    value?: number;
+    conditions?: Record<string, unknown>;
+    usageLimit?: number;
+    maxRedemptionsPerCustomer?: number | null;
+    isActive?: boolean;
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    metadata?: Record<string, unknown>;
+}
+interface DiscountListParams {
+    storeId?: string;
+    isActive?: boolean;
+    code?: string;
+    limit?: number;
+    cursor?: string;
+    sort?: 'asc' | 'desc';
+}
+interface DiscountValidationResult {
+    valid: boolean;
+    discount?: Discount;
+    error?: string;
+}
+interface DiscountPreviewInput {
+    code: string;
+    currency: string;
+    subtotal: number;
+    customerId?: string;
+    lineItems?: Array<{
+        id?: string;
+        quantity: number;
+        unitPrice: number;
+    }>;
+}
+interface DiscountPreviewResult {
+    valid: boolean;
+    code: string;
+    type?: DiscountType;
+    value?: number;
+    currency: string;
+    subtotal: number;
+    discountTotal: number;
+    total: number;
+    discount?: Discount;
+    message: string | null;
+}
+interface Cart {
+    id: string;
+    currency: string;
+    subtotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    taxTotal: number;
+    total: number;
+    discountCode?: string | null;
+    appliedDiscount?: {
+        discountId?: string | null;
+        code: string;
+        type: DiscountType;
+        amount: number;
+        currency: string;
+        freeShipping: boolean;
+        validUntil: string | null;
+        snapshotHash: string;
+    } | null;
+    [key: string]: unknown;
+}
+interface DiscountsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+interface PaginatedDiscounts {
+    data: Discount[];
+    pagination?: {
+        cursor: string | null;
+        hasMore: boolean;
+    };
+}
+
+declare class DiscountsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: DiscountsClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    private requestEnvelope;
+    create(input: CreateDiscountInput): Promise<Discount>;
+    list(params?: DiscountListParams): Promise<PaginatedDiscounts>;
+    get(id: string): Promise<Discount>;
+    update(id: string, input: UpdateDiscountInput): Promise<Discount>;
+    delete(id: string): Promise<void>;
+    validate(code: string, orderTotal: number, customerId?: string): Promise<DiscountValidationResult>;
+    preview(input: DiscountPreviewInput): Promise<DiscountPreviewResult>;
+    applyToCart(cartId: string, code: string): Promise<Cart>;
+    removeFromCart(cartId: string): Promise<Cart>;
+}
+declare function createDiscountsClient(opts: DiscountsClientOptions): DiscountsClient;
+
+declare class ThrottleDiscountsError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(args: {
+        code: string;
+        message: string;
+        statusCode: number;
+        details?: unknown;
+    });
+}
+
+export { type Cart, type CreateDiscountInput, type Discount, type DiscountListParams, type DiscountPreviewInput, type DiscountPreviewResult, type DiscountType, type DiscountValidationResult, DiscountsClient, type DiscountsClientOptions, type PaginatedDiscounts, ThrottleDiscountsError, type UpdateDiscountInput, createDiscountsClient };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+type DiscountType = 'percentage' | 'fixed_amount';
+interface Discount {
+    id: string;
+    code: string | null;
+    name: string;
+    type: DiscountType;
+    value: number;
+    conditions: Record<string, unknown>;
+    usageLimit?: number | null;
+    usageCount: number;
+    maxRedemptionsPerCustomer?: number | null;
+    isActive: boolean;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+interface CreateDiscountInput {
+    storeId?: string;
+    code?: string;
+    name: string;
+    type: DiscountType;
+    value: number;
+    conditions?: Record<string, unknown>;
+    usageLimit?: number;
+    maxRedemptionsPerCustomer?: number | null;
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    metadata?: Record<string, unknown>;
+}
+interface UpdateDiscountInput {
+    name?: string;
+    value?: number;
+    conditions?: Record<string, unknown>;
+    usageLimit?: number;
+    maxRedemptionsPerCustomer?: number | null;
+    isActive?: boolean;
+    startsAt?: string | Date;
+    endsAt?: string | Date;
+    metadata?: Record<string, unknown>;
+}
+interface DiscountListParams {
+    storeId?: string;
+    isActive?: boolean;
+    code?: string;
+    limit?: number;
+    cursor?: string;
+    sort?: 'asc' | 'desc';
+}
+interface DiscountValidationResult {
+    valid: boolean;
+    discount?: Discount;
+    error?: string;
+}
+interface DiscountPreviewInput {
+    code: string;
+    currency: string;
+    subtotal: number;
+    customerId?: string;
+    lineItems?: Array<{
+        id?: string;
+        quantity: number;
+        unitPrice: number;
+    }>;
+}
+interface DiscountPreviewResult {
+    valid: boolean;
+    code: string;
+    type?: DiscountType;
+    value?: number;
+    currency: string;
+    subtotal: number;
+    discountTotal: number;
+    total: number;
+    discount?: Discount;
+    message: string | null;
+}
+interface Cart {
+    id: string;
+    currency: string;
+    subtotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    taxTotal: number;
+    total: number;
+    discountCode?: string | null;
+    appliedDiscount?: {
+        discountId?: string | null;
+        code: string;
+        type: DiscountType;
+        amount: number;
+        currency: string;
+        freeShipping: boolean;
+        validUntil: string | null;
+        snapshotHash: string;
+    } | null;
+    [key: string]: unknown;
+}
+interface DiscountsClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+interface PaginatedDiscounts {
+    data: Discount[];
+    pagination?: {
+        cursor: string | null;
+        hasMore: boolean;
+    };
+}
+
+declare class DiscountsClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: DiscountsClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    private requestEnvelope;
+    create(input: CreateDiscountInput): Promise<Discount>;
+    list(params?: DiscountListParams): Promise<PaginatedDiscounts>;
+    get(id: string): Promise<Discount>;
+    update(id: string, input: UpdateDiscountInput): Promise<Discount>;
+    delete(id: string): Promise<void>;
+    validate(code: string, orderTotal: number, customerId?: string): Promise<DiscountValidationResult>;
+    preview(input: DiscountPreviewInput): Promise<DiscountPreviewResult>;
+    applyToCart(cartId: string, code: string): Promise<Cart>;
+    removeFromCart(cartId: string): Promise<Cart>;
+}
+declare function createDiscountsClient(opts: DiscountsClientOptions): DiscountsClient;
+
+declare class ThrottleDiscountsError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(args: {
+        code: string;
+        message: string;
+        statusCode: number;
+        details?: unknown;
+    });
+}
+
+export { type Cart, type CreateDiscountInput, type Discount, type DiscountListParams, type DiscountPreviewInput, type DiscountPreviewResult, type DiscountType, type DiscountValidationResult, DiscountsClient, type DiscountsClientOptions, type PaginatedDiscounts, ThrottleDiscountsError, type UpdateDiscountInput, createDiscountsClient };

package/dist/index.js

@@ -0,0 +1,134 @@
+// src/errors.ts
+var ThrottleDiscountsError = class extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(args) {
+    super(args.message);
+    this.name = "ThrottleDiscountsError";
+    this.code = args.code;
+    this.statusCode = args.statusCode;
+    this.details = args.details;
+  }
+};
+
+// src/client.ts
+var DiscountsClient = class {
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  timeoutMs;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("DiscountsClient: apiKey is required");
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    if (!fetchImpl) throw new Error("DiscountsClient: fetch is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://api.usethrottle.dev").replace(/\/+$/, "");
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+  }
+  async request(method, path, body) {
+    const envelope = await this.requestEnvelope(method, path, body);
+    return envelope.data;
+  }
+  async requestEnvelope(method, path, body) {
+    const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          "x-api-key": this.apiKey,
+          "content-type": "application/json"
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: ctrl.signal
+      });
+      const json = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new ThrottleDiscountsError({
+          code: json?.error?.code ?? "unknown_error",
+          message: json?.error?.message ?? `HTTP ${res.status}`,
+          statusCode: res.status,
+          details: json?.error?.details
+        });
+      }
+      return {
+        data: json.data,
+        meta: json.meta
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  create(input) {
+    return this.request("POST", "/api/v1/discounts", serializeDates(input));
+  }
+  async list(params = {}) {
+    const query = new URLSearchParams();
+    if (params.storeId) query.set("storeId", params.storeId);
+    if (params.isActive !== void 0) query.set("isActive", String(params.isActive));
+    if (params.code) query.set("code", params.code);
+    if (params.limit !== void 0) query.set("limit", String(params.limit));
+    if (params.cursor) query.set("cursor", params.cursor);
+    if (params.sort) query.set("sort", params.sort);
+    const suffix = query.toString() ? `?${query}` : "";
+    const envelope = await this.requestEnvelope("GET", `/api/v1/discounts${suffix}`);
+    return {
+      data: envelope.data,
+      pagination: envelope.meta?.pagination ?? void 0
+    };
+  }
+  get(id) {
+    return this.request("GET", `/api/v1/discounts/${encodeURIComponent(id)}`);
+  }
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `/api/v1/discounts/${encodeURIComponent(id)}`,
+      serializeDates(input)
+    );
+  }
+  delete(id) {
+    return this.request("DELETE", `/api/v1/discounts/${encodeURIComponent(id)}`);
+  }
+  validate(code, orderTotal, customerId) {
+    return this.request("POST", "/api/v1/discounts/validate", {
+      code,
+      orderTotal,
+      ...customerId ? { customerId } : {}
+    });
+  }
+  preview(input) {
+    return this.request("POST", "/api/v1/discounts/preview", input);
+  }
+  applyToCart(cartId, code) {
+    return this.request(
+      "POST",
+      `/api/v1/carts/${encodeURIComponent(cartId)}/apply-discount`,
+      {
+        code
+      }
+    );
+  }
+  removeFromCart(cartId) {
+    return this.request("DELETE", `/api/v1/carts/${encodeURIComponent(cartId)}/discount`);
+  }
+};
+function createDiscountsClient(opts) {
+  return new DiscountsClient(opts);
+}
+function serializeDates(input) {
+  const out = { ...input };
+  for (const key of ["startsAt", "endsAt"]) {
+    const value = out[key];
+    if (value instanceof Date) out[key] = value.toISOString();
+  }
+  return out;
+}
+export {
+  DiscountsClient,
+  ThrottleDiscountsError,
+  createDiscountsClient
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@usethrottle/discounts",
+  "version": "0.1.0",
+  "description": "Headless TypeScript client for Throttle discount and promotion code APIs.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "CLAUDE.md"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}