fresh-squeezy 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,541 @@
+/**
+ * Core public types for fresh-squeezy.
+ *
+ * These shapes are the integration contract with consuming products. Treat them
+ * as public API surface — breaking changes require a major version bump.
+ */
+/**
+ * Severity for validator findings.
+ *
+ * - `info`: benign observation (e.g. "store reachable").
+ * - `warning`: likely misconfiguration that should be reviewed.
+ * - `error`: the setup is wrong; consumers should fail CI.
+ */
+type ValidationSeverity = "info" | "warning" | "error";
+/**
+ * Which Lemon Squeezy environment a validator ran against.
+ * Mode is determined by which API key was used, not by a host switch.
+ */
+type Mode = "test" | "live";
+/**
+ * A single finding surfaced by a validator.
+ *
+ * `code` is a stable identifier so consumers can match in CI or dashboards
+ * without depending on `message` wording. `suggestedFix` is optional prose
+ * pointing to the most likely remediation.
+ */
+interface ValidationIssue {
+    code: string;
+    severity: ValidationSeverity;
+    message: string;
+    suggestedFix?: string;
+    context?: Record<string, string | number | boolean | null>;
+}
+/**
+ * Return shape for every validator.
+ *
+ * `ok` is `false` if any issue has `severity: "error"`. `mode` surfaces the
+ * environment the validator actually talked to, so callers can detect
+ * test/live confusion.
+ */
+interface ValidationResult<T = unknown> {
+    ok: boolean;
+    mode: Mode;
+    name: string;
+    resource?: T;
+    issues: ValidationIssue[];
+}
+/**
+ * Aggregate doctor output. Composes the results of every individual validator
+ * into one object suitable for CI exit-code decisions, dashboards, or JSON logs.
+ */
+interface DoctorReport {
+    ok: boolean;
+    mode: Mode;
+    results: ValidationResult[];
+}
+/**
+ * Options used when constructing the client.
+ * Every field has an env-based default so consumers can use `createFreshSqueezy()`
+ * with no arguments for the common case.
+ */
+interface FreshSqueezyConfig {
+    apiKey?: string;
+    storeId?: string | number;
+    mode?: Mode;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Resolved config after env + defaults are applied. Internal — not exported
+ * from the package root.
+ */
+interface ResolvedConfig {
+    apiKey: string;
+    storeId?: string;
+    mode: Mode;
+    baseUrl: string;
+    fetch: typeof fetch;
+}
+/**
+ * JSON:API resource envelope returned by the Lemon Squeezy main API.
+ *
+ * The shape is documented at https://jsonapi.org/ and covers the subset
+ * fresh-squeezy relies on.
+ */
+interface JsonApiResource<TAttributes = Record<string, unknown>> {
+    type: string;
+    id: string;
+    attributes: TAttributes;
+    relationships?: Record<string, unknown>;
+    links?: Record<string, string>;
+}
+/**
+ * JSON:API top-level document for single-resource responses.
+ */
+interface JsonApiDocument<TAttributes = Record<string, unknown>> {
+    data: JsonApiResource<TAttributes>;
+    links?: Record<string, string>;
+    meta?: Record<string, unknown>;
+}
+/**
+ * JSON:API top-level document for collection responses.
+ */
+interface JsonApiCollection<TAttributes = Record<string, unknown>> {
+    data: JsonApiResource<TAttributes>[];
+    links?: Record<string, string>;
+    meta?: {
+        page?: {
+            currentPage: number;
+            lastPage: number;
+            total: number;
+        };
+    };
+}
+
+/**
+ * Options for a single HTTP request.
+ *
+ * `path` is a Lemon Squeezy API path starting with `/v1/...`. The `query`
+ * record is serialized as URL search params with JSON:API-style bracketed
+ * keys left untouched (e.g. `filter[store_id]`).
+ */
+interface RequestOptions {
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+/**
+ * Low-level HTTP client. Callers usually go through resource/validator helpers,
+ * but this is also exposed as the public escape hatch so consumers can reach
+ * endpoints fresh-squeezy does not wrap yet.
+ *
+ * Responsibilities kept in this one place (per plan.md "one source of truth
+ * for transport"):
+ *   - auth header injection
+ *   - query string serialization with JSON:API bracket keys preserved
+ *   - response parsing + error normalization
+ *   - surfacing HTTP status in `FreshSqueezyError`
+ *
+ * Retries, pagination helpers, and rate-limit handling live in separate files
+ * so this layer stays small and obvious.
+ */
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Fetch a single JSON:API resource and return its `data` object.
+     */
+    getResource<TAttr>(path: string): Promise<JsonApiResource<TAttr>>;
+    /**
+     * Fetch a JSON:API collection and return its `data` array.
+     * Pagination is the caller's responsibility — use `meta.page` on the raw
+     * request for multi-page traversal.
+     */
+    getCollection<TAttr>(path: string, query?: RequestOptions["query"]): Promise<JsonApiResource<TAttr>[]>;
+    private buildUrl;
+}
+
+/**
+ * Subset of the Lemon Squeezy `users` resource attributes we rely on.
+ * Full schema at https://docs.lemonsqueezy.com/api/users.
+ */
+interface UserAttributes {
+    name: string;
+    email: string;
+    color?: string;
+    avatar_url?: string | null;
+    has_custom_avatar?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Document-level metadata on `/v1/users/me`.
+ *
+ * `test_mode` was added to the endpoint on 2024-01-05 (per the Lemon Squeezy
+ * API changelog: https://docs.lemonsqueezy.com/api/getting-started/changelog).
+ * It reports whether the *key* being used is a test-mode key, independent of
+ * what the caller declared. The connection validator compares this against
+ * the caller's declared mode to catch the common "prod key in staging"
+ * (or vice versa) misconfiguration.
+ */
+interface UserMeta {
+    test_mode?: boolean;
+}
+/**
+ * Authenticated-user document with the `data` + `meta` block preserved.
+ * The connection validator needs the meta flag, so we return the full
+ * document here rather than just `data` as the collection helpers do.
+ */
+type AuthenticatedUserDocument = JsonApiDocument<UserAttributes> & {
+    meta?: UserMeta;
+};
+/**
+ * Fetch the user associated with the API key. Primary use is the connection
+ * validator: a successful call confirms the key is valid, surfaces the
+ * account identity for logs, and exposes `meta.test_mode` for mode
+ * mismatch detection.
+ */
+declare function getAuthenticatedUser(http: HttpClient): Promise<AuthenticatedUserDocument>;
+/**
+ * Backwards-compatible helper if a caller only wants the resource (old
+ * `getAuthenticatedUser` shape). Internal — not re-exported from the root.
+ */
+declare function userResource(doc: AuthenticatedUserDocument): JsonApiResource<UserAttributes>;
+
+/**
+ * Connection validator summary attached to the `resource` field. Keeps the
+ * validator self-contained — consumers need not call `users/me` again.
+ *
+ * `actualMode` is derived from the `meta.test_mode` field Lemon Squeezy added
+ * to `/v1/users/me` on 2024-01-05 (API changelog). When the caller declared
+ * one mode but the key actually belongs to the other, the validator fires a
+ * `MODE_MISMATCH` error — the single misconfiguration most likely to cause a
+ * prod-in-staging (or vice versa) incident.
+ */
+interface ConnectionSummary {
+    user: UserAttributes;
+    storeCount: number;
+    storeIds: string[];
+    /** The mode the API key actually belongs to (per `/v1/users/me` meta). */
+    actualMode?: Mode;
+    /** The mode the caller asked for at construction time. */
+    declaredMode: Mode;
+}
+/**
+ * Verify that the API key works, surface the account identity + reachable
+ * stores, and cross-check declared mode vs the key's true mode.
+ *
+ * This is the first check every `doctor()` run performs; if it fails,
+ * no downstream validator has anything useful to report.
+ */
+declare function validateConnection(http: HttpClient, mode: Mode): Promise<ValidationResult<ConnectionSummary>>;
+
+/**
+ * Subset of product attributes we need for validation. `status` drives the
+ * "unpublished product" check; `store_id` drives ownership checks.
+ */
+interface ProductAttributes {
+    name: string;
+    slug: string;
+    description?: string | null;
+    status: "draft" | "published";
+    status_formatted?: string;
+    store_id: number;
+    buy_now_url?: string | null;
+    from_price?: number | null;
+    to_price?: number | null;
+    created_at?: string;
+    updated_at?: string;
+}
+declare function getProduct(http: HttpClient, productId: string | number): Promise<JsonApiResource<ProductAttributes>>;
+declare function listProducts(http: HttpClient, storeId: string | number): Promise<JsonApiResource<ProductAttributes>[]>;
+
+interface ProductValidationOptions {
+    productId: string | number;
+    /** Optional: confirm the product belongs to this store. */
+    expectedStoreId?: string | number;
+}
+/**
+ * Validate a product's publish state, store ownership, and that it has at
+ * least one published variant. Surfaces the most common misconfigurations
+ * caught in the wild (unpublished product, wrong store, missing variants).
+ */
+declare function validateProduct(http: HttpClient, mode: Mode, options: ProductValidationOptions): Promise<ValidationResult<ProductAttributes>>;
+
+/**
+ * Subset of webhook attributes we read. `events` is an ordered list of
+ * subscribed event names; the validator cross-references these against the
+ * support manifest to catch missing subscriptions.
+ */
+interface WebhookAttributes {
+    store_id: number;
+    url: string;
+    events: string[];
+    last_sent_at?: string | null;
+    created_at?: string;
+    updated_at?: string;
+    test_mode?: boolean;
+}
+declare function listWebhooksForStore(http: HttpClient, storeId: string | number): Promise<JsonApiResource<WebhookAttributes>[]>;
+
+interface WebhookValidationOptions {
+    storeId: string | number;
+    /** The public URL your app exposes for Lemon Squeezy to POST to. */
+    url: string;
+}
+/**
+ * Confirm a webhook matching `options.url` is registered against the given
+ * store, and cross-reference its subscribed events against the support
+ * manifest's recommended + optional lists.
+ *
+ * Missing recommended events = error. Missing optional events = info, because
+ * not every integration needs them.
+ */
+declare function validateWebhook(http: HttpClient, mode: Mode, options: WebhookValidationOptions): Promise<ValidationResult<WebhookAttributes>>;
+
+/**
+ * Optional targets for the doctor run. If a target is omitted, its validator
+ * is skipped — consumers only pay for what they configure.
+ */
+interface DoctorOptions {
+    storeId?: string | number;
+    productId?: string | number;
+    webhookUrl?: string;
+}
+/**
+ * Compose every configured validator into a single report. This is the
+ * primary entry point for CI health checks: one call, one structured result,
+ * one exit code decision.
+ *
+ * Order is meaningful. Connection runs first because downstream validators
+ * have nothing useful to say if the API key is broken.
+ */
+declare function doctor(http: HttpClient, mode: Mode, options?: DoctorOptions): Promise<DoctorReport>;
+
+/**
+ * Subset of store attributes fresh-squeezy reads.
+ * Full schema at https://docs.lemonsqueezy.com/api/stores.
+ */
+interface StoreAttributes {
+    name: string;
+    slug: string;
+    domain?: string | null;
+    url?: string | null;
+    country?: string;
+    currency?: string;
+    plan?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+declare function getStore(http: HttpClient, storeId: string | number): Promise<JsonApiResource<StoreAttributes>>;
+declare function listStores(http: HttpClient): Promise<JsonApiResource<StoreAttributes>[]>;
+
+/**
+ * The public client. All consumer code flows through the factory below —
+ * direct instantiation is intentionally not exposed so we can evolve the
+ * internals without breaking callers.
+ */
+interface FreshSqueezyClient {
+    /** Resolved mode (test or live). Surfaced so consumers can log it. */
+    readonly mode: Mode;
+    /** Raw HTTP escape hatch for endpoints fresh-squeezy does not wrap. */
+    request<T = unknown>(options: RequestOptions): Promise<T>;
+    validateConnection(): Promise<ValidationResult<ConnectionSummary>>;
+    validateStore(storeId: string | number): Promise<ValidationResult<StoreAttributes>>;
+    validateProduct(options: ProductValidationOptions): Promise<ValidationResult<ProductAttributes>>;
+    validateWebhook(options: WebhookValidationOptions): Promise<ValidationResult<WebhookAttributes>>;
+    doctor(options?: DoctorOptions): Promise<DoctorReport>;
+}
+/**
+ * Create a fresh-squeezy client. Zero-config usage reads
+ * `LEMON_SQUEEZY_API_KEY`, `LEMON_SQUEEZY_STORE_ID`, and `LEMON_SQUEEZY_MODE`
+ * from `process.env`.
+ *
+ * @example
+ * ```ts
+ * const lemon = createFreshSqueezy();
+ * const report = await lemon.doctor();
+ * if (!report.ok) process.exit(1);
+ * ```
+ */
+declare function createFreshSqueezy(config?: FreshSqueezyConfig): FreshSqueezyClient;
+
+/**
+ * Unified error type for fresh-squeezy. All HTTP and validation failures that
+ * bubble up to consumers pass through this class so caller code can branch on
+ * a single `instanceof` check.
+ *
+ * Why a class over a discriminated union: Node's `fetch` rejections interleave
+ * with library errors in user stack traces. A class keeps the stack readable
+ * and gives one stable prototype chain for consumer `catch` blocks.
+ */
+declare class FreshSqueezyError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly detail?: unknown;
+    constructor(opts: {
+        code: string;
+        message: string;
+        status?: number;
+        detail?: unknown;
+    });
+}
+
+/**
+ * Env variable names read when a field is not passed explicitly. Consuming
+ * products rely on these names being stable — treat them as public API.
+ */
+declare const ENV_KEYS: {
+    readonly apiKey: "LEMON_SQUEEZY_API_KEY";
+    readonly storeId: "LEMON_SQUEEZY_STORE_ID";
+    readonly mode: "LEMON_SQUEEZY_MODE";
+};
+/**
+ * Resolve the user-supplied config against environment variables and defaults.
+ *
+ * Precedence (highest → lowest): explicit argument → env var → built-in default.
+ * Throws `FreshSqueezyError` only for fields that cannot be defaulted (currently
+ * just `apiKey`), so callers can surface a clear setup error at construction
+ * time rather than at first request.
+ */
+declare function resolveConfig(input?: FreshSqueezyConfig): ResolvedConfig;
+
+/**
+ * Stable issue codes. Consumers may switch on these in CI — do not rename
+ * without a major version bump.
+ */
+declare const ISSUE_CODES: {
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    readonly MODE_MISMATCH: "MODE_MISMATCH";
+    readonly STORE_NOT_FOUND: "STORE_NOT_FOUND";
+    readonly STORE_NOT_OWNED: "STORE_NOT_OWNED";
+    readonly PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND";
+    readonly PRODUCT_WRONG_STORE: "PRODUCT_WRONG_STORE";
+    readonly PRODUCT_UNPUBLISHED: "PRODUCT_UNPUBLISHED";
+    readonly PRODUCT_NO_BUY_URL: "PRODUCT_NO_BUY_URL";
+    readonly VARIANT_UNPUBLISHED: "VARIANT_UNPUBLISHED";
+    readonly VARIANT_MISSING: "VARIANT_MISSING";
+    readonly WEBHOOK_NOT_FOUND: "WEBHOOK_NOT_FOUND";
+    readonly WEBHOOK_EVENTS_MISSING: "WEBHOOK_EVENTS_MISSING";
+    readonly WEBHOOK_OPTIONAL_EVENTS: "WEBHOOK_OPTIONAL_EVENTS";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly UNKNOWN: "UNKNOWN";
+};
+/**
+ * Build a `ValidationIssue` with defaults for the common case.
+ * Extracted so every validator produces consistently shaped issues.
+ */
+declare function issue(code: string, severity: ValidationSeverity, message: string, extras?: {
+    suggestedFix?: string;
+    context?: ValidationIssue["context"];
+}): ValidationIssue;
+/**
+ * Fold an issue list into a boolean. Used by every validator so `ok` is
+ * computed the same way everywhere.
+ */
+declare function isOk(issues: ValidationIssue[]): boolean;
+/**
+ * Compose a `ValidationResult` with the `ok` flag derived from issues.
+ */
+declare function buildResult<T>(name: string, mode: ValidationResult["mode"], issues: ValidationIssue[], resource?: T): ValidationResult<T>;
+
+/**
+ * Variant attributes used by the product validator to detect
+ * variant/price drift from the product they belong to.
+ */
+interface VariantAttributes {
+    product_id: number;
+    name: string;
+    slug: string;
+    description?: string | null;
+    status: "pending" | "draft" | "published";
+    is_subscription?: boolean;
+    interval?: string | null;
+    interval_count?: number | null;
+    has_license_keys?: boolean;
+    created_at?: string;
+    updated_at?: string;
+}
+declare function listVariantsForProduct(http: HttpClient, productId: string | number): Promise<JsonApiResource<VariantAttributes>[]>;
+
+/**
+ * Support manifest: the locally reviewed source of truth for what
+ * fresh-squeezy explicitly understands on the Lemon Squeezy platform.
+ *
+ * The plan deliberately favors a static, reviewed manifest over live changelog
+ * scraping (see plan.md §Non-goals). When the platform adds new resources,
+ * fields, or webhook events, bump the entries below and re-snapshot the
+ * changelog page with `npm run check:changelog -- --update`.
+ *
+ * Changelog source: https://docs.lemonsqueezy.com/api/getting-started/changelog
+ * Last reviewed:    2026-04-24
+ */
+/**
+ * Resources fresh-squeezy wraps today. Anything outside this list is still
+ * reachable via the raw `request()` escape hatch but has no dedicated
+ * validator.
+ */
+declare const SUPPORTED_RESOURCES: readonly ["users", "stores", "products", "variants", "webhooks"];
+/**
+ * Webhook events fresh-squeezy expects a production integration to subscribe to
+ * at minimum. Consumers can still subscribe to more; the validator only flags
+ * missing ones from this list.
+ *
+ * Rationale:
+ *   - `order_*` covers one-off purchases and refunds.
+ *   - `subscription_*` covers the recurring-billing lifecycle.
+ *   - `subscription_payment_*` covers dunning / retry loops.
+ *
+ * Confirmed present in the Lemon Squeezy webhook topic list as of 2026-04-24.
+ */
+declare const RECOMMENDED_WEBHOOK_EVENTS: readonly ["order_created", "order_refunded", "subscription_created", "subscription_updated", "subscription_cancelled", "subscription_resumed", "subscription_expired", "subscription_payment_success", "subscription_payment_failed"];
+/**
+ * Newer or integration-specific events surfaced as info-level suggestions
+ * rather than errors. Missing these is common and not necessarily a
+ * misconfiguration.
+ *
+ * Per-entry changelog provenance (source:
+ * https://docs.lemonsqueezy.com/api/getting-started/changelog):
+ *
+ *   - `customer_updated` — added 2026-02-25. Fires when a customer record
+ *     changes (e.g. email, marketing consent). Needed if the app mirrors
+ *     customer data locally.
+ *   - `affiliate_activated` — added 2025-01-21 alongside the affiliates
+ *     endpoints. Only relevant if the store has an affiliate program.
+ *   - `license_key_created` / `license_key_updated` — License API events.
+ *     Only relevant when variants have `has_license_keys: true`.
+ */
+declare const OPTIONAL_WEBHOOK_EVENTS: readonly ["customer_updated", "affiliate_activated", "license_key_created", "license_key_updated"];
+/**
+ * Platform additions we have read and decided *not* to validate against yet,
+ * documented here so maintainers see the deliberate gap during review.
+ *
+ * Tracked so the drift workflow has an "expected state" to compare against:
+ * if the changelog page changes and none of these items explain it, the diff
+ * is probably something new that needs a manifest update.
+ */
+declare const ACKNOWLEDGED_CHANGELOG_ENTRIES: readonly [{
+    readonly date: "2026-02-25";
+    readonly summary: "Added customer_updated webhook event.";
+    readonly handledBy: "OPTIONAL_WEBHOOK_EVENTS";
+}, {
+    readonly date: "2025-06-11";
+    readonly summary: "Added payment_processor attribute to Subscription objects.";
+    readonly handledBy: "Not wrapped — reachable via client.request('/v1/subscriptions/:id'). Add a validator only if a real integration needs it.";
+}, {
+    readonly date: "2025-01-21";
+    readonly summary: "Added Affiliates endpoints and affiliate_activated webhook.";
+    readonly handledBy: "OPTIONAL_WEBHOOK_EVENTS (event only; resource stays v2 scope)";
+}, {
+    readonly date: "2024-01-05";
+    readonly summary: "Added test_mode flag to /v1/users/me meta.";
+    readonly handledBy: "Read in validateConnection to emit MODE_MISMATCH when the key's true mode differs from the caller's declared mode.";
+}];
+type RecommendedEvent = (typeof RECOMMENDED_WEBHOOK_EVENTS)[number];
+type OptionalEvent = (typeof OPTIONAL_WEBHOOK_EVENTS)[number];
+
+export { ACKNOWLEDGED_CHANGELOG_ENTRIES, type AuthenticatedUserDocument, type ConnectionSummary, type DoctorOptions, type DoctorReport, ENV_KEYS, type FreshSqueezyClient, type FreshSqueezyConfig, FreshSqueezyError, ISSUE_CODES, type JsonApiCollection, type JsonApiDocument, type JsonApiResource, type Mode, OPTIONAL_WEBHOOK_EVENTS, type OptionalEvent, type ProductAttributes, type ProductValidationOptions, RECOMMENDED_WEBHOOK_EVENTS, type RecommendedEvent, type ResolvedConfig, SUPPORTED_RESOURCES, type StoreAttributes, type UserAttributes, type UserMeta, type ValidationIssue, type ValidationResult, type ValidationSeverity, type VariantAttributes, type WebhookAttributes, type WebhookValidationOptions, buildResult, createFreshSqueezy, doctor, getAuthenticatedUser, getProduct, getStore, isOk, issue, listProducts, listStores, listVariantsForProduct, listWebhooksForStore, resolveConfig, userResource, validateConnection, validateProduct, validateWebhook };