fresh-squeezy 0.1.0

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/core/errors.ts","../src/core/config.ts","../src/core/http.ts","../src/resources/users.ts","../src/resources/stores.ts","../src/validate/rules.ts","../src/validate/connection.ts","../src/validate/store.ts","../src/resources/products.ts","../src/resources/variants.ts","../src/validate/product.ts","../src/resources/webhooks.ts","../src/support/manifest.ts","../src/validate/webhook.ts","../src/validate/doctor.ts","../src/createFreshSqueezy.ts"],"sourcesContent":["export * from \"./createFreshSqueezy.js\";\nexport * from \"./core/errors.js\";\nexport * from \"./core/config.js\";\nexport * from \"./core/types.js\";\nexport * from \"./validate/rules.js\";\nexport * from \"./validate/connection.js\";\nexport * from \"./validate/product.js\";\nexport * from \"./validate/webhook.js\";\nexport * from \"./validate/doctor.js\";\nexport * from \"./resources/stores.js\";\nexport * from \"./resources/products.js\";\nexport * from \"./resources/variants.js\";\nexport * from \"./resources/webhooks.js\";\nexport * from \"./resources/users.js\";\nexport * from \"./support/manifest.js\";\n","/**\n * Unified error type for fresh-squeezy. All HTTP and validation failures that\n * bubble up to consumers pass through this class so caller code can branch on\n * a single `instanceof` check.\n *\n * Why a class over a discriminated union: Node's `fetch` rejections interleave\n * with library errors in user stack traces. A class keeps the stack readable\n * and gives one stable prototype chain for consumer `catch` blocks.\n */\nexport class FreshSqueezyError extends Error {\n  public readonly code: string;\n  public readonly status?: number;\n  public readonly detail?: unknown;\n\n  constructor(opts: { code: string; message: string; status?: number; detail?: unknown }) {\n    super(opts.message);\n    this.name = \"FreshSqueezyError\";\n    this.code = opts.code;\n    this.status = opts.status;\n    this.detail = opts.detail;\n    Object.setPrototypeOf(this, FreshSqueezyError.prototype);\n  }\n}\n","import type { FreshSqueezyConfig, Mode, ResolvedConfig } from \"./types.js\";\nimport { FreshSqueezyError } from \"./errors.js\";\n\n/**\n * Lemon Squeezy API root. Test and live share the same host — mode is determined\n * by which API key is used. Documented at https://docs.lemonsqueezy.com/api.\n */\nconst DEFAULT_BASE_URL = \"https://api.lemonsqueezy.com\";\n\n/**\n * Env variable names read when a field is not passed explicitly. Consuming\n * products rely on these names being stable — treat them as public API.\n */\nexport const ENV_KEYS = {\n  apiKey: \"LEMON_SQUEEZY_API_KEY\",\n  storeId: \"LEMON_SQUEEZY_STORE_ID\",\n  mode: \"LEMON_SQUEEZY_MODE\",\n} as const;\n\n/**\n * Resolve the user-supplied config against environment variables and defaults.\n *\n * Precedence (highest → lowest): explicit argument → env var → built-in default.\n * Throws `FreshSqueezyError` only for fields that cannot be defaulted (currently\n * just `apiKey`), so callers can surface a clear setup error at construction\n * time rather than at first request.\n */\nexport function resolveConfig(input: FreshSqueezyConfig = {}): ResolvedConfig {\n  const apiKey = input.apiKey ?? process.env[ENV_KEYS.apiKey];\n  if (!apiKey) {\n    throw new FreshSqueezyError({\n      code: \"MISSING_API_KEY\",\n      message: `No API key provided. Pass \\`apiKey\\` or set ${ENV_KEYS.apiKey}.`,\n    });\n  }\n\n  const mode = normalizeMode(input.mode ?? process.env[ENV_KEYS.mode] ?? \"test\");\n  const storeIdRaw = input.storeId ?? process.env[ENV_KEYS.storeId];\n\n  return {\n    apiKey,\n    storeId: storeIdRaw == null ? undefined : String(storeIdRaw),\n    mode,\n    baseUrl: input.baseUrl ?? DEFAULT_BASE_URL,\n    fetch: input.fetch ?? globalThis.fetch,\n  };\n}\n\nfunction normalizeMode(value: string): Mode {\n  if (value === \"test\" || value === \"live\") return value;\n  throw new FreshSqueezyError({\n    code: \"INVALID_MODE\",\n    message: `Mode must be \"test\" or \"live\", got \"${value}\".`,\n  });\n}\n","import { FreshSqueezyError } from \"./errors.js\";\nimport type {\n  JsonApiCollection,\n  JsonApiDocument,\n  JsonApiResource,\n  ResolvedConfig,\n} from \"./types.js\";\n\n/**\n * Options for a single HTTP request.\n *\n * `path` is a Lemon Squeezy API path starting with `/v1/...`. The `query`\n * record is serialized as URL search params with JSON:API-style bracketed\n * keys left untouched (e.g. `filter[store_id]`).\n */\nexport interface RequestOptions {\n  method?: \"GET\" | \"POST\" | \"PATCH\" | \"DELETE\";\n  path: string;\n  query?: Record<string, string | number | undefined>;\n  body?: Record<string, unknown>;\n  signal?: AbortSignal;\n}\n\n/**\n * Lemon Squeezy JSON:API error object. Kept loose because the API occasionally\n * includes extra keys; the fields we surface are the stable ones.\n */\ninterface JsonApiError {\n  status?: string;\n  code?: string;\n  title?: string;\n  detail?: string;\n}\n\n/**\n * Low-level HTTP client. Callers usually go through resource/validator helpers,\n * but this is also exposed as the public escape hatch so consumers can reach\n * endpoints fresh-squeezy does not wrap yet.\n *\n * Responsibilities kept in this one place (per plan.md \"one source of truth\n * for transport\"):\n *   - auth header injection\n *   - query string serialization with JSON:API bracket keys preserved\n *   - response parsing + error normalization\n *   - surfacing HTTP status in `FreshSqueezyError`\n *\n * Retries, pagination helpers, and rate-limit handling live in separate files\n * so this layer stays small and obvious.\n */\nexport class HttpClient {\n  constructor(private readonly config: ResolvedConfig) {}\n\n  async request<T>(options: RequestOptions): Promise<T> {\n    const url = this.buildUrl(options.path, options.query);\n    const headers: Record<string, string> = {\n      Authorization: `Bearer ${this.config.apiKey}`,\n      Accept: \"application/vnd.api+json\",\n    };\n    if (options.body !== undefined) {\n      headers[\"Content-Type\"] = \"application/vnd.api+json\";\n    }\n\n    let response: Response;\n    try {\n      response = await this.config.fetch(url, {\n        method: options.method ?? \"GET\",\n        headers,\n        body: options.body === undefined ? undefined : JSON.stringify(options.body),\n        signal: options.signal,\n      });\n    } catch (cause) {\n      throw new FreshSqueezyError({\n        code: \"NETWORK_ERROR\",\n        message: cause instanceof Error ? cause.message : \"Network request failed\",\n        detail: cause,\n      });\n    }\n\n    const text = await response.text();\n    const parsed = text.length > 0 ? safeJsonParse(text) : undefined;\n\n    if (!response.ok) {\n      throw toApiError(response.status, parsed);\n    }\n\n    return parsed as T;\n  }\n\n  /**\n   * Fetch a single JSON:API resource and return its `data` object.\n   */\n  async getResource<TAttr>(path: string): Promise<JsonApiResource<TAttr>> {\n    const doc = await this.request<JsonApiDocument<TAttr>>({ path });\n    return doc.data;\n  }\n\n  /**\n   * Fetch a JSON:API collection and return its `data` array.\n   * Pagination is the caller's responsibility — use `meta.page` on the raw\n   * request for multi-page traversal.\n   */\n  async getCollection<TAttr>(\n    path: string,\n    query?: RequestOptions[\"query\"]\n  ): Promise<JsonApiResource<TAttr>[]> {\n    const doc = await this.request<JsonApiCollection<TAttr>>({ path, query });\n    return doc.data;\n  }\n\n  private buildUrl(path: string, query?: RequestOptions[\"query\"]): string {\n    const url = new URL(path, this.config.baseUrl);\n    if (query) {\n      for (const [key, value] of Object.entries(query)) {\n        if (value === undefined) continue;\n        url.searchParams.append(key, String(value));\n      }\n    }\n    return url.toString();\n  }\n}\n\nfunction safeJsonParse(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\nfunction toApiError(status: number, body: unknown): FreshSqueezyError {\n  const errors = extractJsonApiErrors(body);\n  const first = errors[0];\n  const code =\n    status === 401\n      ? \"UNAUTHORIZED\"\n      : status === 404\n        ? \"NOT_FOUND\"\n        : status === 429\n          ? \"RATE_LIMITED\"\n          : (first?.code ?? `HTTP_${status}`);\n  const message =\n    first?.detail ?? first?.title ?? `Lemon Squeezy request failed with status ${status}`;\n  return new FreshSqueezyError({ code, status, message, detail: body });\n}\n\nfunction extractJsonApiErrors(body: unknown): JsonApiError[] {\n  if (!body || typeof body !== \"object\") return [];\n  const errors = (body as { errors?: unknown }).errors;\n  if (!Array.isArray(errors)) return [];\n  return errors.filter(\n    (entry): entry is JsonApiError => typeof entry === \"object\" && entry !== null\n  );\n}\n","import type { HttpClient } from \"../core/http.js\";\nimport type { JsonApiDocument, JsonApiResource } from \"../core/types.js\";\n\n/**\n * Subset of the Lemon Squeezy `users` resource attributes we rely on.\n * Full schema at https://docs.lemonsqueezy.com/api/users.\n */\nexport interface UserAttributes {\n  name: string;\n  email: string;\n  color?: string;\n  avatar_url?: string | null;\n  has_custom_avatar?: boolean;\n  createdAt?: string;\n  updatedAt?: string;\n}\n\n/**\n * Document-level metadata on `/v1/users/me`.\n *\n * `test_mode` was added to the endpoint on 2024-01-05 (per the Lemon Squeezy\n * API changelog: https://docs.lemonsqueezy.com/api/getting-started/changelog).\n * It reports whether the *key* being used is a test-mode key, independent of\n * what the caller declared. The connection validator compares this against\n * the caller's declared mode to catch the common \"prod key in staging\"\n * (or vice versa) misconfiguration.\n */\nexport interface UserMeta {\n  test_mode?: boolean;\n}\n\n/**\n * Authenticated-user document with the `data` + `meta` block preserved.\n * The connection validator needs the meta flag, so we return the full\n * document here rather than just `data` as the collection helpers do.\n */\nexport type AuthenticatedUserDocument = JsonApiDocument<UserAttributes> & { meta?: UserMeta };\n\n/**\n * Fetch the user associated with the API key. Primary use is the connection\n * validator: a successful call confirms the key is valid, surfaces the\n * account identity for logs, and exposes `meta.test_mode` for mode\n * mismatch detection.\n */\nexport async function getAuthenticatedUser(\n  http: HttpClient\n): Promise<AuthenticatedUserDocument> {\n  return http.request<AuthenticatedUserDocument>({ path: \"/v1/users/me\" });\n}\n\n/**\n * Backwards-compatible helper if a caller only wants the resource (old\n * `getAuthenticatedUser` shape). Internal — not re-exported from the root.\n */\nexport function userResource(\n  doc: AuthenticatedUserDocument\n): JsonApiResource<UserAttributes> {\n  return doc.data;\n}\n","import type { HttpClient } from \"../core/http.js\";\nimport type { JsonApiResource } from \"../core/types.js\";\n\n/**\n * Subset of store attributes fresh-squeezy reads.\n * Full schema at https://docs.lemonsqueezy.com/api/stores.\n */\nexport interface StoreAttributes {\n  name: string;\n  slug: string;\n  domain?: string | null;\n  url?: string | null;\n  country?: string;\n  currency?: string;\n  plan?: string;\n  created_at?: string;\n  updated_at?: string;\n}\n\nexport async function getStore(\n  http: HttpClient,\n  storeId: string | number\n): Promise<JsonApiResource<StoreAttributes>> {\n  return http.getResource<StoreAttributes>(`/v1/stores/${storeId}`);\n}\n\nexport async function listStores(http: HttpClient): Promise<JsonApiResource<StoreAttributes>[]> {\n  return http.getCollection<StoreAttributes>(\"/v1/stores\");\n}\n","import type { ValidationIssue, ValidationResult, ValidationSeverity } from \"../core/types.js\";\n\n/**\n * Stable issue codes. Consumers may switch on these in CI — do not rename\n * without a major version bump.\n */\nexport const ISSUE_CODES = {\n  AUTH_FAILED: \"AUTH_FAILED\",\n  MODE_MISMATCH: \"MODE_MISMATCH\",\n  STORE_NOT_FOUND: \"STORE_NOT_FOUND\",\n  STORE_NOT_OWNED: \"STORE_NOT_OWNED\",\n  PRODUCT_NOT_FOUND: \"PRODUCT_NOT_FOUND\",\n  PRODUCT_WRONG_STORE: \"PRODUCT_WRONG_STORE\",\n  PRODUCT_UNPUBLISHED: \"PRODUCT_UNPUBLISHED\",\n  PRODUCT_NO_BUY_URL: \"PRODUCT_NO_BUY_URL\",\n  VARIANT_UNPUBLISHED: \"VARIANT_UNPUBLISHED\",\n  VARIANT_MISSING: \"VARIANT_MISSING\",\n  WEBHOOK_NOT_FOUND: \"WEBHOOK_NOT_FOUND\",\n  WEBHOOK_EVENTS_MISSING: \"WEBHOOK_EVENTS_MISSING\",\n  WEBHOOK_OPTIONAL_EVENTS: \"WEBHOOK_OPTIONAL_EVENTS\",\n  NETWORK_ERROR: \"NETWORK_ERROR\",\n  UNKNOWN: \"UNKNOWN\",\n} as const;\n\n/**\n * Build a `ValidationIssue` with defaults for the common case.\n * Extracted so every validator produces consistently shaped issues.\n */\nexport function issue(\n  code: string,\n  severity: ValidationSeverity,\n  message: string,\n  extras: { suggestedFix?: string; context?: ValidationIssue[\"context\"] } = {}\n): ValidationIssue {\n  const base: ValidationIssue = { code, severity, message };\n  if (extras.suggestedFix !== undefined) base.suggestedFix = extras.suggestedFix;\n  if (extras.context !== undefined) base.context = extras.context;\n  return base;\n}\n\n/**\n * Fold an issue list into a boolean. Used by every validator so `ok` is\n * computed the same way everywhere.\n */\nexport function isOk(issues: ValidationIssue[]): boolean {\n  return !issues.some((entry) => entry.severity === \"error\");\n}\n\n/**\n * Compose a `ValidationResult` with the `ok` flag derived from issues.\n */\nexport function buildResult<T>(\n  name: string,\n  mode: ValidationResult[\"mode\"],\n  issues: ValidationIssue[],\n  resource?: T\n): ValidationResult<T> {\n  const result: ValidationResult<T> = {\n    name,\n    ok: isOk(issues),\n    mode,\n    issues,\n  };\n  if (resource !== undefined) result.resource = resource;\n  return result;\n}\n","import { FreshSqueezyError } from \"../core/errors.js\";\nimport type { HttpClient } from \"../core/http.js\";\nimport type { Mode, ValidationIssue, ValidationResult } from \"../core/types.js\";\nimport { getAuthenticatedUser, type UserAttributes } from \"../resources/users.js\";\nimport { listStores } from \"../resources/stores.js\";\nimport { ISSUE_CODES, buildResult, issue } from \"./rules.js\";\n\n/**\n * Connection validator summary attached to the `resource` field. Keeps the\n * validator self-contained — consumers need not call `users/me` again.\n *\n * `actualMode` is derived from the `meta.test_mode` field Lemon Squeezy added\n * to `/v1/users/me` on 2024-01-05 (API changelog). When the caller declared\n * one mode but the key actually belongs to the other, the validator fires a\n * `MODE_MISMATCH` error — the single misconfiguration most likely to cause a\n * prod-in-staging (or vice versa) incident.\n */\nexport interface ConnectionSummary {\n  user: UserAttributes;\n  storeCount: number;\n  storeIds: string[];\n  /** The mode the API key actually belongs to (per `/v1/users/me` meta). */\n  actualMode?: Mode;\n  /** The mode the caller asked for at construction time. */\n  declaredMode: Mode;\n}\n\n/**\n * Verify that the API key works, surface the account identity + reachable\n * stores, and cross-check declared mode vs the key's true mode.\n *\n * This is the first check every `doctor()` run performs; if it fails,\n * no downstream validator has anything useful to report.\n */\nexport async function validateConnection(\n  http: HttpClient,\n  mode: Mode\n): Promise<ValidationResult<ConnectionSummary>> {\n  const issues: ValidationIssue[] = [];\n\n  try {\n    const userDoc = await getAuthenticatedUser(http);\n    const stores = await listStores(http);\n\n    const actualMode = resolveActualMode(userDoc.meta?.test_mode);\n    const summary: ConnectionSummary = {\n      user: userDoc.data.attributes,\n      storeCount: stores.length,\n      storeIds: stores.map((store) => store.id),\n      declaredMode: mode,\n      ...(actualMode ? { actualMode } : {}),\n    };\n\n    if (actualMode && actualMode !== mode) {\n      issues.push(\n        issue(\n          ISSUE_CODES.MODE_MISMATCH,\n          \"error\",\n          `API key is a ${actualMode}-mode key but was run with --mode ${mode}.`,\n          {\n            suggestedFix: `Either pass --mode ${actualMode} or use a ${mode}-mode key from https://app.lemonsqueezy.com/settings/api.`,\n            context: { declared: mode, actual: actualMode },\n          }\n        )\n      );\n    }\n\n    if (stores.length === 0) {\n      issues.push(\n        issue(\n          ISSUE_CODES.STORE_NOT_FOUND,\n          \"warning\",\n          \"API key authenticated but no stores are reachable.\",\n          { suggestedFix: \"Confirm the API key belongs to an account that owns at least one store.\" }\n        )\n      );\n    }\n\n    return buildResult(\"connection\", mode, issues, summary);\n  } catch (err) {\n    issues.push(toConnectionIssue(err));\n    return buildResult(\"connection\", mode, issues);\n  }\n}\n\n/**\n * Map the boolean `meta.test_mode` flag to our `Mode` type. Returns\n * `undefined` when the field is absent so older accounts / proxies that\n * don't surface it don't produce spurious MODE_MISMATCH failures.\n */\nfunction resolveActualMode(testMode: boolean | undefined): Mode | undefined {\n  if (testMode === true) return \"test\";\n  if (testMode === false) return \"live\";\n  return undefined;\n}\n\nfunction toConnectionIssue(err: unknown): ValidationIssue {\n  if (err instanceof FreshSqueezyError) {\n    if (err.code === \"UNAUTHORIZED\") {\n      return issue(ISSUE_CODES.AUTH_FAILED, \"error\", \"API key rejected by Lemon Squeezy.\", {\n        suggestedFix: \"Regenerate the key at https://app.lemonsqueezy.com/settings/api.\",\n        context: { status: err.status ?? null },\n      });\n    }\n    if (err.code === \"NETWORK_ERROR\") {\n      return issue(ISSUE_CODES.NETWORK_ERROR, \"error\", `Could not reach Lemon Squeezy: ${err.message}`);\n    }\n    return issue(ISSUE_CODES.UNKNOWN, \"error\", err.message, {\n      context: { status: err.status ?? null, code: err.code },\n    });\n  }\n  const message = err instanceof Error ? err.message : \"Unknown error\";\n  return issue(ISSUE_CODES.UNKNOWN, \"error\", message);\n}\n","import { FreshSqueezyError } from \"../core/errors.js\";\nimport type { HttpClient } from \"../core/http.js\";\nimport type { Mode, ValidationIssue, ValidationResult } from \"../core/types.js\";\nimport { getStore, type StoreAttributes } from \"../resources/stores.js\";\nimport { ISSUE_CODES, buildResult, issue } from \"./rules.js\";\n\n/**\n * Verify a store exists and is reachable with the current API key. A 404\n * typically means the key belongs to a different account, not that the store\n * is gone — the suggested fix reflects that.\n */\nexport async function validateStore(\n  http: HttpClient,\n  mode: Mode,\n  storeId: string | number\n): Promise<ValidationResult<StoreAttributes>> {\n  const issues: ValidationIssue[] = [];\n\n  try {\n    const store = await getStore(http, storeId);\n    return buildResult(\"store\", mode, issues, store.attributes);\n  } catch (err) {\n    if (err instanceof FreshSqueezyError && err.status === 404) {\n      issues.push(\n        issue(\n          ISSUE_CODES.STORE_NOT_FOUND,\n          \"error\",\n          `Store ${storeId} not found with the current API key.`,\n          {\n            suggestedFix:\n              \"Check the store ID and confirm the API key belongs to the account that owns it.\",\n            context: { storeId: String(storeId) },\n          }\n        )\n      );\n      return buildResult(\"store\", mode, issues);\n    }\n    if (err instanceof FreshSqueezyError) {\n      issues.push(\n        issue(ISSUE_CODES.UNKNOWN, \"error\", err.message, {\n          context: { status: err.status ?? null, code: err.code },\n        })\n      );\n      return buildResult(\"store\", mode, issues);\n    }\n    const message = err instanceof Error ? err.message : \"Unknown error\";\n    issues.push(issue(ISSUE_CODES.UNKNOWN, \"error\", message));\n    return buildResult(\"store\", mode, issues);\n  }\n}\n","import type { HttpClient } from \"../core/http.js\";\nimport type { JsonApiResource } from \"../core/types.js\";\n\n/**\n * Subset of product attributes we need for validation. `status` drives the\n * \"unpublished product\" check; `store_id` drives ownership checks.\n */\nexport interface ProductAttributes {\n  name: string;\n  slug: string;\n  description?: string | null;\n  status: \"draft\" | \"published\";\n  status_formatted?: string;\n  store_id: number;\n  buy_now_url?: string | null;\n  from_price?: number | null;\n  to_price?: number | null;\n  created_at?: string;\n  updated_at?: string;\n}\n\nexport async function getProduct(\n  http: HttpClient,\n  productId: string | number\n): Promise<JsonApiResource<ProductAttributes>> {\n  return http.getResource<ProductAttributes>(`/v1/products/${productId}`);\n}\n\nexport async function listProducts(\n  http: HttpClient,\n  storeId: string | number\n): Promise<JsonApiResource<ProductAttributes>[]> {\n  return http.getCollection<ProductAttributes>(\"/v1/products\", {\n    \"filter[store_id]\": String(storeId),\n  });\n}\n","import type { HttpClient } from \"../core/http.js\";\nimport type { JsonApiResource } from \"../core/types.js\";\n\n/**\n * Variant attributes used by the product validator to detect\n * variant/price drift from the product they belong to.\n */\nexport interface VariantAttributes {\n  product_id: number;\n  name: string;\n  slug: string;\n  description?: string | null;\n  status: \"pending\" | \"draft\" | \"published\";\n  is_subscription?: boolean;\n  interval?: string | null;\n  interval_count?: number | null;\n  has_license_keys?: boolean;\n  created_at?: string;\n  updated_at?: string;\n}\n\nexport async function listVariantsForProduct(\n  http: HttpClient,\n  productId: string | number\n): Promise<JsonApiResource<VariantAttributes>[]> {\n  return http.getCollection<VariantAttributes>(\"/v1/variants\", {\n    \"filter[product_id]\": String(productId),\n  });\n}\n","import { FreshSqueezyError } from \"../core/errors.js\";\nimport type { HttpClient } from \"../core/http.js\";\nimport type { Mode, ValidationIssue, ValidationResult } from \"../core/types.js\";\nimport { getProduct, type ProductAttributes } from \"../resources/products.js\";\nimport { listVariantsForProduct } from \"../resources/variants.js\";\nimport { ISSUE_CODES, buildResult, issue } from \"./rules.js\";\n\nexport interface ProductValidationOptions {\n  productId: string | number;\n  /** Optional: confirm the product belongs to this store. */\n  expectedStoreId?: string | number;\n}\n\n/**\n * Validate a product's publish state, store ownership, and that it has at\n * least one published variant. Surfaces the most common misconfigurations\n * caught in the wild (unpublished product, wrong store, missing variants).\n */\nexport async function validateProduct(\n  http: HttpClient,\n  mode: Mode,\n  options: ProductValidationOptions\n): Promise<ValidationResult<ProductAttributes>> {\n  const issues: ValidationIssue[] = [];\n\n  let product;\n  try {\n    product = await getProduct(http, options.productId);\n  } catch (err) {\n    if (err instanceof FreshSqueezyError && err.status === 404) {\n      issues.push(\n        issue(\n          ISSUE_CODES.PRODUCT_NOT_FOUND,\n          \"error\",\n          `Product ${options.productId} not found.`,\n          {\n            suggestedFix: \"Verify the product ID in the Lemon Squeezy dashboard.\",\n            context: { productId: String(options.productId) },\n          }\n        )\n      );\n      return buildResult(\"product\", mode, issues);\n    }\n    const message = err instanceof Error ? err.message : \"Unknown error\";\n    issues.push(issue(ISSUE_CODES.UNKNOWN, \"error\", message));\n    return buildResult(\"product\", mode, issues);\n  }\n\n  const attrs = product.attributes;\n\n  if (options.expectedStoreId !== undefined) {\n    const expected = String(options.expectedStoreId);\n    const actual = String(attrs.store_id);\n    if (expected !== actual) {\n      issues.push(\n        issue(\n          ISSUE_CODES.PRODUCT_WRONG_STORE,\n          \"error\",\n          `Product belongs to store ${actual}, expected ${expected}.`,\n          {\n            suggestedFix:\n              \"Either use the correct store ID or the correct product ID — IDs should not cross stores.\",\n            context: { expectedStoreId: expected, actualStoreId: actual },\n          }\n        )\n      );\n    }\n  }\n\n  if (attrs.status !== \"published\") {\n    issues.push(\n      issue(\n        ISSUE_CODES.PRODUCT_UNPUBLISHED,\n        \"error\",\n        `Product is in \"${attrs.status}\" state, not \"published\".`,\n        {\n          suggestedFix: \"Publish the product in the Lemon Squeezy dashboard before selling.\",\n          context: { status: attrs.status },\n        }\n      )\n    );\n  }\n\n  if (!attrs.buy_now_url) {\n    issues.push(\n      issue(\n        ISSUE_CODES.PRODUCT_NO_BUY_URL,\n        \"warning\",\n        \"Product has no buy-now URL. Hosted checkout may be disabled.\",\n        { suggestedFix: \"Enable buy-now in product settings, or use a custom checkout flow.\" }\n      )\n    );\n  }\n\n  try {\n    const variants = await listVariantsForProduct(http, options.productId);\n    if (variants.length === 0) {\n      issues.push(\n        issue(\n          ISSUE_CODES.VARIANT_MISSING,\n          \"error\",\n          \"Product has no variants. Customers cannot purchase it.\",\n          { suggestedFix: \"Add at least one variant in the product configuration.\" }\n        )\n      );\n    } else if (!variants.some((variant) => variant.attributes.status === \"published\")) {\n      issues.push(\n        issue(\n          ISSUE_CODES.VARIANT_UNPUBLISHED,\n          \"error\",\n          \"Product has variants but none are published.\",\n          { suggestedFix: \"Publish at least one variant.\" }\n        )\n      );\n    }\n  } catch (err) {\n    const message = err instanceof Error ? err.message : \"Unknown error fetching variants\";\n    issues.push(issue(ISSUE_CODES.UNKNOWN, \"warning\", message));\n  }\n\n  return buildResult(\"product\", mode, issues, attrs);\n}\n","import type { HttpClient } from \"../core/http.js\";\nimport type { JsonApiResource } from \"../core/types.js\";\n\n/**\n * Subset of webhook attributes we read. `events` is an ordered list of\n * subscribed event names; the validator cross-references these against the\n * support manifest to catch missing subscriptions.\n */\nexport interface WebhookAttributes {\n  store_id: number;\n  url: string;\n  events: string[];\n  last_sent_at?: string | null;\n  created_at?: string;\n  updated_at?: string;\n  test_mode?: boolean;\n}\n\nexport async function listWebhooksForStore(\n  http: HttpClient,\n  storeId: string | number\n): Promise<JsonApiResource<WebhookAttributes>[]> {\n  return http.getCollection<WebhookAttributes>(\"/v1/webhooks\", {\n    \"filter[store_id]\": String(storeId),\n  });\n}\n","/**\n * Support manifest: the locally reviewed source of truth for what\n * fresh-squeezy explicitly understands on the Lemon Squeezy platform.\n *\n * The plan deliberately favors a static, reviewed manifest over live changelog\n * scraping (see plan.md §Non-goals). When the platform adds new resources,\n * fields, or webhook events, bump the entries below and re-snapshot the\n * changelog page with `npm run check:changelog -- --update`.\n *\n * Changelog source: https://docs.lemonsqueezy.com/api/getting-started/changelog\n * Last reviewed:    2026-04-24\n */\n\n/**\n * Resources fresh-squeezy wraps today. Anything outside this list is still\n * reachable via the raw `request()` escape hatch but has no dedicated\n * validator.\n */\nexport const SUPPORTED_RESOURCES = [\n  \"users\",\n  \"stores\",\n  \"products\",\n  \"variants\",\n  \"webhooks\",\n] as const;\n\n/**\n * Webhook events fresh-squeezy expects a production integration to subscribe to\n * at minimum. Consumers can still subscribe to more; the validator only flags\n * missing ones from this list.\n *\n * Rationale:\n *   - `order_*` covers one-off purchases and refunds.\n *   - `subscription_*` covers the recurring-billing lifecycle.\n *   - `subscription_payment_*` covers dunning / retry loops.\n *\n * Confirmed present in the Lemon Squeezy webhook topic list as of 2026-04-24.\n */\nexport const RECOMMENDED_WEBHOOK_EVENTS = [\n  \"order_created\",\n  \"order_refunded\",\n  \"subscription_created\",\n  \"subscription_updated\",\n  \"subscription_cancelled\",\n  \"subscription_resumed\",\n  \"subscription_expired\",\n  \"subscription_payment_success\",\n  \"subscription_payment_failed\",\n] as const;\n\n/**\n * Newer or integration-specific events surfaced as info-level suggestions\n * rather than errors. Missing these is common and not necessarily a\n * misconfiguration.\n *\n * Per-entry changelog provenance (source:\n * https://docs.lemonsqueezy.com/api/getting-started/changelog):\n *\n *   - `customer_updated` — added 2026-02-25. Fires when a customer record\n *     changes (e.g. email, marketing consent). Needed if the app mirrors\n *     customer data locally.\n *   - `affiliate_activated` — added 2025-01-21 alongside the affiliates\n *     endpoints. Only relevant if the store has an affiliate program.\n *   - `license_key_created` / `license_key_updated` — License API events.\n *     Only relevant when variants have `has_license_keys: true`.\n */\nexport const OPTIONAL_WEBHOOK_EVENTS = [\n  \"customer_updated\",\n  \"affiliate_activated\",\n  \"license_key_created\",\n  \"license_key_updated\",\n] as const;\n\n/**\n * Platform additions we have read and decided *not* to validate against yet,\n * documented here so maintainers see the deliberate gap during review.\n *\n * Tracked so the drift workflow has an \"expected state\" to compare against:\n * if the changelog page changes and none of these items explain it, the diff\n * is probably something new that needs a manifest update.\n */\nexport const ACKNOWLEDGED_CHANGELOG_ENTRIES = [\n  {\n    date: \"2026-02-25\",\n    summary: \"Added customer_updated webhook event.\",\n    handledBy: \"OPTIONAL_WEBHOOK_EVENTS\",\n  },\n  {\n    date: \"2025-06-11\",\n    summary: \"Added payment_processor attribute to Subscription objects.\",\n    handledBy:\n      \"Not wrapped — reachable via client.request('/v1/subscriptions/:id'). Add a validator only if a real integration needs it.\",\n  },\n  {\n    date: \"2025-01-21\",\n    summary: \"Added Affiliates endpoints and affiliate_activated webhook.\",\n    handledBy: \"OPTIONAL_WEBHOOK_EVENTS (event only; resource stays v2 scope)\",\n  },\n  {\n    date: \"2024-01-05\",\n    summary: \"Added test_mode flag to /v1/users/me meta.\",\n    handledBy:\n      \"Read in validateConnection to emit MODE_MISMATCH when the key's true mode differs from the caller's declared mode.\",\n  },\n] as const;\n\nexport type RecommendedEvent = (typeof RECOMMENDED_WEBHOOK_EVENTS)[number];\nexport type OptionalEvent = (typeof OPTIONAL_WEBHOOK_EVENTS)[number];\n","import { FreshSqueezyError } from \"../core/errors.js\";\nimport type { HttpClient } from \"../core/http.js\";\nimport type { Mode, ValidationIssue, ValidationResult } from \"../core/types.js\";\nimport { listWebhooksForStore, type WebhookAttributes } from \"../resources/webhooks.js\";\nimport { OPTIONAL_WEBHOOK_EVENTS, RECOMMENDED_WEBHOOK_EVENTS } from \"../support/manifest.js\";\nimport { ISSUE_CODES, buildResult, issue } from \"./rules.js\";\n\nexport interface WebhookValidationOptions {\n  storeId: string | number;\n  /** The public URL your app exposes for Lemon Squeezy to POST to. */\n  url: string;\n}\n\n/**\n * Confirm a webhook matching `options.url` is registered against the given\n * store, and cross-reference its subscribed events against the support\n * manifest's recommended + optional lists.\n *\n * Missing recommended events = error. Missing optional events = info, because\n * not every integration needs them.\n */\nexport async function validateWebhook(\n  http: HttpClient,\n  mode: Mode,\n  options: WebhookValidationOptions\n): Promise<ValidationResult<WebhookAttributes>> {\n  const issues: ValidationIssue[] = [];\n\n  let webhooks;\n  try {\n    webhooks = await listWebhooksForStore(http, options.storeId);\n  } catch (err) {\n    if (err instanceof FreshSqueezyError) {\n      issues.push(\n        issue(ISSUE_CODES.UNKNOWN, \"error\", err.message, {\n          context: { status: err.status ?? null, code: err.code },\n        })\n      );\n      return buildResult(\"webhook\", mode, issues);\n    }\n    const message = err instanceof Error ? err.message : \"Unknown error\";\n    issues.push(issue(ISSUE_CODES.UNKNOWN, \"error\", message));\n    return buildResult(\"webhook\", mode, issues);\n  }\n\n  const match = webhooks.find((webhook) => normalizeUrl(webhook.attributes.url) === normalizeUrl(options.url));\n  if (!match) {\n    issues.push(\n      issue(\n        ISSUE_CODES.WEBHOOK_NOT_FOUND,\n        \"error\",\n        `No webhook registered for URL ${options.url} on store ${options.storeId}.`,\n        {\n          suggestedFix:\n            \"Register the webhook in Lemon Squeezy (Settings → Webhooks) and subscribe to the recommended events.\",\n          context: { storeId: String(options.storeId), url: options.url },\n        }\n      )\n    );\n    return buildResult(\"webhook\", mode, issues);\n  }\n\n  const subscribed = new Set(match.attributes.events);\n  const missingRecommended = RECOMMENDED_WEBHOOK_EVENTS.filter((event) => !subscribed.has(event));\n  const missingOptional = OPTIONAL_WEBHOOK_EVENTS.filter((event) => !subscribed.has(event));\n\n  if (missingRecommended.length > 0) {\n    issues.push(\n      issue(\n        ISSUE_CODES.WEBHOOK_EVENTS_MISSING,\n        \"error\",\n        `Webhook is missing recommended events: ${missingRecommended.join(\", \")}.`,\n        {\n          suggestedFix: \"Subscribe to all recommended events so the integration survives plan changes and refunds.\",\n          context: { missing: missingRecommended.join(\",\") },\n        }\n      )\n    );\n  }\n\n  if (missingOptional.length > 0) {\n    issues.push(\n      issue(\n        ISSUE_CODES.WEBHOOK_OPTIONAL_EVENTS,\n        \"info\",\n        `Optional events not subscribed: ${missingOptional.join(\", \")}.`,\n        { context: { missing: missingOptional.join(\",\") } }\n      )\n    );\n  }\n\n  return buildResult(\"webhook\", mode, issues, match.attributes);\n}\n\n/**\n * Compare webhook URLs without being tripped up by trailing slashes.\n * Lemon Squeezy strips trailing slashes on save; users often pass them in.\n */\nfunction normalizeUrl(raw: string): string {\n  return raw.replace(/\\/+$/, \"\").toLowerCase();\n}\n","import type { HttpClient } from \"../core/http.js\";\nimport type { DoctorReport, Mode, ValidationResult } from \"../core/types.js\";\nimport { validateConnection } from \"./connection.js\";\nimport { validateStore } from \"./store.js\";\nimport { validateProduct } from \"./product.js\";\nimport { validateWebhook } from \"./webhook.js\";\n\n/**\n * Optional targets for the doctor run. If a target is omitted, its validator\n * is skipped — consumers only pay for what they configure.\n */\nexport interface DoctorOptions {\n  storeId?: string | number;\n  productId?: string | number;\n  webhookUrl?: string;\n}\n\n/**\n * Compose every configured validator into a single report. This is the\n * primary entry point for CI health checks: one call, one structured result,\n * one exit code decision.\n *\n * Order is meaningful. Connection runs first because downstream validators\n * have nothing useful to say if the API key is broken.\n */\nexport async function doctor(\n  http: HttpClient,\n  mode: Mode,\n  options: DoctorOptions = {}\n): Promise<DoctorReport> {\n  const results: ValidationResult[] = [];\n\n  const connection = await validateConnection(http, mode);\n  results.push(connection);\n\n  if (!connection.ok) {\n    return { ok: false, mode, results };\n  }\n\n  if (options.storeId !== undefined) {\n    results.push(await validateStore(http, mode, options.storeId));\n  }\n\n  if (options.productId !== undefined) {\n    results.push(\n      await validateProduct(http, mode, {\n        productId: options.productId,\n        expectedStoreId: options.storeId,\n      })\n    );\n  }\n\n  if (options.storeId !== undefined && options.webhookUrl !== undefined) {\n    results.push(\n      await validateWebhook(http, mode, {\n        storeId: options.storeId,\n        url: options.webhookUrl,\n      })\n    );\n  }\n\n  const ok = results.every((result) => result.ok);\n  return { ok, mode, results };\n}\n","import { resolveConfig } from \"./core/config.js\";\nimport { HttpClient, type RequestOptions } from \"./core/http.js\";\nimport type { FreshSqueezyConfig, DoctorReport, Mode, ValidationResult } from \"./core/types.js\";\nimport { validateConnection, type ConnectionSummary } from \"./validate/connection.js\";\nimport { validateStore } from \"./validate/store.js\";\nimport { validateProduct, type ProductValidationOptions } from \"./validate/product.js\";\nimport { validateWebhook, type WebhookValidationOptions } from \"./validate/webhook.js\";\nimport { doctor, type DoctorOptions } from \"./validate/doctor.js\";\nimport type { StoreAttributes } from \"./resources/stores.js\";\nimport type { ProductAttributes } from \"./resources/products.js\";\nimport type { WebhookAttributes } from \"./resources/webhooks.js\";\n\n/**\n * The public client. All consumer code flows through the factory below —\n * direct instantiation is intentionally not exposed so we can evolve the\n * internals without breaking callers.\n */\nexport interface FreshSqueezyClient {\n  /** Resolved mode (test or live). Surfaced so consumers can log it. */\n  readonly mode: Mode;\n\n  /** Raw HTTP escape hatch for endpoints fresh-squeezy does not wrap. */\n  request<T = unknown>(options: RequestOptions): Promise<T>;\n\n  validateConnection(): Promise<ValidationResult<ConnectionSummary>>;\n  validateStore(storeId: string | number): Promise<ValidationResult<StoreAttributes>>;\n  validateProduct(options: ProductValidationOptions): Promise<ValidationResult<ProductAttributes>>;\n  validateWebhook(options: WebhookValidationOptions): Promise<ValidationResult<WebhookAttributes>>;\n  doctor(options?: DoctorOptions): Promise<DoctorReport>;\n}\n\n/**\n * Create a fresh-squeezy client. Zero-config usage reads\n * `LEMON_SQUEEZY_API_KEY`, `LEMON_SQUEEZY_STORE_ID`, and `LEMON_SQUEEZY_MODE`\n * from `process.env`.\n *\n * @example\n * ```ts\n * const lemon = createFreshSqueezy();\n * const report = await lemon.doctor();\n * if (!report.ok) process.exit(1);\n * ```\n */\nexport function createFreshSqueezy(config: FreshSqueezyConfig = {}): FreshSqueezyClient {\n  const resolved = resolveConfig(config);\n  const http = new HttpClient(resolved);\n\n  return {\n    mode: resolved.mode,\n    request: (options) => http.request(options),\n    validateConnection: () => validateConnection(http, resolved.mode),\n    validateStore: (storeId) => validateStore(http, resolved.mode, storeId),\n    validateProduct: (options) => validateProduct(http, resolved.mode, options),\n    validateWebhook: (options) => validateWebhook(http, resolved.mode, options),\n    doctor: (options) =>\n      doctor(http, resolved.mode, {\n        storeId: options?.storeId ?? resolved.storeId,\n        productId: options?.productId,\n        webhookUrl: options?.webhookUrl,\n      }),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -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 };