fresh-squeezy 0.1.0

package/dist/index.js

@@ -0,0 +1,599 @@
+// src/core/errors.ts
+var FreshSqueezyError = class _FreshSqueezyError extends Error {
+  code;
+  status;
+  detail;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "FreshSqueezyError";
+    this.code = opts.code;
+    this.status = opts.status;
+    this.detail = opts.detail;
+    Object.setPrototypeOf(this, _FreshSqueezyError.prototype);
+  }
+};
+
+// src/core/config.ts
+var DEFAULT_BASE_URL = "https://api.lemonsqueezy.com";
+var ENV_KEYS = {
+  apiKey: "LEMON_SQUEEZY_API_KEY",
+  storeId: "LEMON_SQUEEZY_STORE_ID",
+  mode: "LEMON_SQUEEZY_MODE"
+};
+function resolveConfig(input = {}) {
+  const apiKey = input.apiKey ?? process.env[ENV_KEYS.apiKey];
+  if (!apiKey) {
+    throw new FreshSqueezyError({
+      code: "MISSING_API_KEY",
+      message: `No API key provided. Pass \`apiKey\` or set ${ENV_KEYS.apiKey}.`
+    });
+  }
+  const mode = normalizeMode(input.mode ?? process.env[ENV_KEYS.mode] ?? "test");
+  const storeIdRaw = input.storeId ?? process.env[ENV_KEYS.storeId];
+  return {
+    apiKey,
+    storeId: storeIdRaw == null ? void 0 : String(storeIdRaw),
+    mode,
+    baseUrl: input.baseUrl ?? DEFAULT_BASE_URL,
+    fetch: input.fetch ?? globalThis.fetch
+  };
+}
+function normalizeMode(value) {
+  if (value === "test" || value === "live") return value;
+  throw new FreshSqueezyError({
+    code: "INVALID_MODE",
+    message: `Mode must be "test" or "live", got "${value}".`
+  });
+}
+
+// src/core/http.ts
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  async request(options) {
+    const url = this.buildUrl(options.path, options.query);
+    const headers = {
+      Authorization: `Bearer ${this.config.apiKey}`,
+      Accept: "application/vnd.api+json"
+    };
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/vnd.api+json";
+    }
+    let response;
+    try {
+      response = await this.config.fetch(url, {
+        method: options.method ?? "GET",
+        headers,
+        body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+        signal: options.signal
+      });
+    } catch (cause) {
+      throw new FreshSqueezyError({
+        code: "NETWORK_ERROR",
+        message: cause instanceof Error ? cause.message : "Network request failed",
+        detail: cause
+      });
+    }
+    const text = await response.text();
+    const parsed = text.length > 0 ? safeJsonParse(text) : void 0;
+    if (!response.ok) {
+      throw toApiError(response.status, parsed);
+    }
+    return parsed;
+  }
+  /**
+   * Fetch a single JSON:API resource and return its `data` object.
+   */
+  async getResource(path) {
+    const doc = await this.request({ path });
+    return doc.data;
+  }
+  /**
+   * 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.
+   */
+  async getCollection(path, query) {
+    const doc = await this.request({ path, query });
+    return doc.data;
+  }
+  buildUrl(path, query) {
+    const url = new URL(path, this.config.baseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0) continue;
+        url.searchParams.append(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+};
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function toApiError(status, body) {
+  const errors = extractJsonApiErrors(body);
+  const first = errors[0];
+  const code = status === 401 ? "UNAUTHORIZED" : status === 404 ? "NOT_FOUND" : status === 429 ? "RATE_LIMITED" : first?.code ?? `HTTP_${status}`;
+  const message = first?.detail ?? first?.title ?? `Lemon Squeezy request failed with status ${status}`;
+  return new FreshSqueezyError({ code, status, message, detail: body });
+}
+function extractJsonApiErrors(body) {
+  if (!body || typeof body !== "object") return [];
+  const errors = body.errors;
+  if (!Array.isArray(errors)) return [];
+  return errors.filter(
+    (entry) => typeof entry === "object" && entry !== null
+  );
+}
+
+// src/resources/users.ts
+async function getAuthenticatedUser(http) {
+  return http.request({ path: "/v1/users/me" });
+}
+function userResource(doc) {
+  return doc.data;
+}
+
+// src/resources/stores.ts
+async function getStore(http, storeId) {
+  return http.getResource(`/v1/stores/${storeId}`);
+}
+async function listStores(http) {
+  return http.getCollection("/v1/stores");
+}
+
+// src/validate/rules.ts
+var ISSUE_CODES = {
+  AUTH_FAILED: "AUTH_FAILED",
+  MODE_MISMATCH: "MODE_MISMATCH",
+  STORE_NOT_FOUND: "STORE_NOT_FOUND",
+  STORE_NOT_OWNED: "STORE_NOT_OWNED",
+  PRODUCT_NOT_FOUND: "PRODUCT_NOT_FOUND",
+  PRODUCT_WRONG_STORE: "PRODUCT_WRONG_STORE",
+  PRODUCT_UNPUBLISHED: "PRODUCT_UNPUBLISHED",
+  PRODUCT_NO_BUY_URL: "PRODUCT_NO_BUY_URL",
+  VARIANT_UNPUBLISHED: "VARIANT_UNPUBLISHED",
+  VARIANT_MISSING: "VARIANT_MISSING",
+  WEBHOOK_NOT_FOUND: "WEBHOOK_NOT_FOUND",
+  WEBHOOK_EVENTS_MISSING: "WEBHOOK_EVENTS_MISSING",
+  WEBHOOK_OPTIONAL_EVENTS: "WEBHOOK_OPTIONAL_EVENTS",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  UNKNOWN: "UNKNOWN"
+};
+function issue(code, severity, message, extras = {}) {
+  const base = { code, severity, message };
+  if (extras.suggestedFix !== void 0) base.suggestedFix = extras.suggestedFix;
+  if (extras.context !== void 0) base.context = extras.context;
+  return base;
+}
+function isOk(issues) {
+  return !issues.some((entry) => entry.severity === "error");
+}
+function buildResult(name, mode, issues, resource) {
+  const result = {
+    name,
+    ok: isOk(issues),
+    mode,
+    issues
+  };
+  if (resource !== void 0) result.resource = resource;
+  return result;
+}
+
+// src/validate/connection.ts
+async function validateConnection(http, mode) {
+  const issues = [];
+  try {
+    const userDoc = await getAuthenticatedUser(http);
+    const stores = await listStores(http);
+    const actualMode = resolveActualMode(userDoc.meta?.test_mode);
+    const summary = {
+      user: userDoc.data.attributes,
+      storeCount: stores.length,
+      storeIds: stores.map((store) => store.id),
+      declaredMode: mode,
+      ...actualMode ? { actualMode } : {}
+    };
+    if (actualMode && actualMode !== mode) {
+      issues.push(
+        issue(
+          ISSUE_CODES.MODE_MISMATCH,
+          "error",
+          `API key is a ${actualMode}-mode key but was run with --mode ${mode}.`,
+          {
+            suggestedFix: `Either pass --mode ${actualMode} or use a ${mode}-mode key from https://app.lemonsqueezy.com/settings/api.`,
+            context: { declared: mode, actual: actualMode }
+          }
+        )
+      );
+    }
+    if (stores.length === 0) {
+      issues.push(
+        issue(
+          ISSUE_CODES.STORE_NOT_FOUND,
+          "warning",
+          "API key authenticated but no stores are reachable.",
+          { suggestedFix: "Confirm the API key belongs to an account that owns at least one store." }
+        )
+      );
+    }
+    return buildResult("connection", mode, issues, summary);
+  } catch (err) {
+    issues.push(toConnectionIssue(err));
+    return buildResult("connection", mode, issues);
+  }
+}
+function resolveActualMode(testMode) {
+  if (testMode === true) return "test";
+  if (testMode === false) return "live";
+  return void 0;
+}
+function toConnectionIssue(err) {
+  if (err instanceof FreshSqueezyError) {
+    if (err.code === "UNAUTHORIZED") {
+      return issue(ISSUE_CODES.AUTH_FAILED, "error", "API key rejected by Lemon Squeezy.", {
+        suggestedFix: "Regenerate the key at https://app.lemonsqueezy.com/settings/api.",
+        context: { status: err.status ?? null }
+      });
+    }
+    if (err.code === "NETWORK_ERROR") {
+      return issue(ISSUE_CODES.NETWORK_ERROR, "error", `Could not reach Lemon Squeezy: ${err.message}`);
+    }
+    return issue(ISSUE_CODES.UNKNOWN, "error", err.message, {
+      context: { status: err.status ?? null, code: err.code }
+    });
+  }
+  const message = err instanceof Error ? err.message : "Unknown error";
+  return issue(ISSUE_CODES.UNKNOWN, "error", message);
+}
+
+// src/validate/store.ts
+async function validateStore(http, mode, storeId) {
+  const issues = [];
+  try {
+    const store = await getStore(http, storeId);
+    return buildResult("store", mode, issues, store.attributes);
+  } catch (err) {
+    if (err instanceof FreshSqueezyError && err.status === 404) {
+      issues.push(
+        issue(
+          ISSUE_CODES.STORE_NOT_FOUND,
+          "error",
+          `Store ${storeId} not found with the current API key.`,
+          {
+            suggestedFix: "Check the store ID and confirm the API key belongs to the account that owns it.",
+            context: { storeId: String(storeId) }
+          }
+        )
+      );
+      return buildResult("store", mode, issues);
+    }
+    if (err instanceof FreshSqueezyError) {
+      issues.push(
+        issue(ISSUE_CODES.UNKNOWN, "error", err.message, {
+          context: { status: err.status ?? null, code: err.code }
+        })
+      );
+      return buildResult("store", mode, issues);
+    }
+    const message = err instanceof Error ? err.message : "Unknown error";
+    issues.push(issue(ISSUE_CODES.UNKNOWN, "error", message));
+    return buildResult("store", mode, issues);
+  }
+}
+
+// src/resources/products.ts
+async function getProduct(http, productId) {
+  return http.getResource(`/v1/products/${productId}`);
+}
+async function listProducts(http, storeId) {
+  return http.getCollection("/v1/products", {
+    "filter[store_id]": String(storeId)
+  });
+}
+
+// src/resources/variants.ts
+async function listVariantsForProduct(http, productId) {
+  return http.getCollection("/v1/variants", {
+    "filter[product_id]": String(productId)
+  });
+}
+
+// src/validate/product.ts
+async function validateProduct(http, mode, options) {
+  const issues = [];
+  let product;
+  try {
+    product = await getProduct(http, options.productId);
+  } catch (err) {
+    if (err instanceof FreshSqueezyError && err.status === 404) {
+      issues.push(
+        issue(
+          ISSUE_CODES.PRODUCT_NOT_FOUND,
+          "error",
+          `Product ${options.productId} not found.`,
+          {
+            suggestedFix: "Verify the product ID in the Lemon Squeezy dashboard.",
+            context: { productId: String(options.productId) }
+          }
+        )
+      );
+      return buildResult("product", mode, issues);
+    }
+    const message = err instanceof Error ? err.message : "Unknown error";
+    issues.push(issue(ISSUE_CODES.UNKNOWN, "error", message));
+    return buildResult("product", mode, issues);
+  }
+  const attrs = product.attributes;
+  if (options.expectedStoreId !== void 0) {
+    const expected = String(options.expectedStoreId);
+    const actual = String(attrs.store_id);
+    if (expected !== actual) {
+      issues.push(
+        issue(
+          ISSUE_CODES.PRODUCT_WRONG_STORE,
+          "error",
+          `Product belongs to store ${actual}, expected ${expected}.`,
+          {
+            suggestedFix: "Either use the correct store ID or the correct product ID \u2014 IDs should not cross stores.",
+            context: { expectedStoreId: expected, actualStoreId: actual }
+          }
+        )
+      );
+    }
+  }
+  if (attrs.status !== "published") {
+    issues.push(
+      issue(
+        ISSUE_CODES.PRODUCT_UNPUBLISHED,
+        "error",
+        `Product is in "${attrs.status}" state, not "published".`,
+        {
+          suggestedFix: "Publish the product in the Lemon Squeezy dashboard before selling.",
+          context: { status: attrs.status }
+        }
+      )
+    );
+  }
+  if (!attrs.buy_now_url) {
+    issues.push(
+      issue(
+        ISSUE_CODES.PRODUCT_NO_BUY_URL,
+        "warning",
+        "Product has no buy-now URL. Hosted checkout may be disabled.",
+        { suggestedFix: "Enable buy-now in product settings, or use a custom checkout flow." }
+      )
+    );
+  }
+  try {
+    const variants = await listVariantsForProduct(http, options.productId);
+    if (variants.length === 0) {
+      issues.push(
+        issue(
+          ISSUE_CODES.VARIANT_MISSING,
+          "error",
+          "Product has no variants. Customers cannot purchase it.",
+          { suggestedFix: "Add at least one variant in the product configuration." }
+        )
+      );
+    } else if (!variants.some((variant) => variant.attributes.status === "published")) {
+      issues.push(
+        issue(
+          ISSUE_CODES.VARIANT_UNPUBLISHED,
+          "error",
+          "Product has variants but none are published.",
+          { suggestedFix: "Publish at least one variant." }
+        )
+      );
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown error fetching variants";
+    issues.push(issue(ISSUE_CODES.UNKNOWN, "warning", message));
+  }
+  return buildResult("product", mode, issues, attrs);
+}
+
+// src/resources/webhooks.ts
+async function listWebhooksForStore(http, storeId) {
+  return http.getCollection("/v1/webhooks", {
+    "filter[store_id]": String(storeId)
+  });
+}
+
+// src/support/manifest.ts
+var SUPPORTED_RESOURCES = [
+  "users",
+  "stores",
+  "products",
+  "variants",
+  "webhooks"
+];
+var RECOMMENDED_WEBHOOK_EVENTS = [
+  "order_created",
+  "order_refunded",
+  "subscription_created",
+  "subscription_updated",
+  "subscription_cancelled",
+  "subscription_resumed",
+  "subscription_expired",
+  "subscription_payment_success",
+  "subscription_payment_failed"
+];
+var OPTIONAL_WEBHOOK_EVENTS = [
+  "customer_updated",
+  "affiliate_activated",
+  "license_key_created",
+  "license_key_updated"
+];
+var ACKNOWLEDGED_CHANGELOG_ENTRIES = [
+  {
+    date: "2026-02-25",
+    summary: "Added customer_updated webhook event.",
+    handledBy: "OPTIONAL_WEBHOOK_EVENTS"
+  },
+  {
+    date: "2025-06-11",
+    summary: "Added payment_processor attribute to Subscription objects.",
+    handledBy: "Not wrapped \u2014 reachable via client.request('/v1/subscriptions/:id'). Add a validator only if a real integration needs it."
+  },
+  {
+    date: "2025-01-21",
+    summary: "Added Affiliates endpoints and affiliate_activated webhook.",
+    handledBy: "OPTIONAL_WEBHOOK_EVENTS (event only; resource stays v2 scope)"
+  },
+  {
+    date: "2024-01-05",
+    summary: "Added test_mode flag to /v1/users/me meta.",
+    handledBy: "Read in validateConnection to emit MODE_MISMATCH when the key's true mode differs from the caller's declared mode."
+  }
+];
+
+// src/validate/webhook.ts
+async function validateWebhook(http, mode, options) {
+  const issues = [];
+  let webhooks;
+  try {
+    webhooks = await listWebhooksForStore(http, options.storeId);
+  } catch (err) {
+    if (err instanceof FreshSqueezyError) {
+      issues.push(
+        issue(ISSUE_CODES.UNKNOWN, "error", err.message, {
+          context: { status: err.status ?? null, code: err.code }
+        })
+      );
+      return buildResult("webhook", mode, issues);
+    }
+    const message = err instanceof Error ? err.message : "Unknown error";
+    issues.push(issue(ISSUE_CODES.UNKNOWN, "error", message));
+    return buildResult("webhook", mode, issues);
+  }
+  const match = webhooks.find((webhook) => normalizeUrl(webhook.attributes.url) === normalizeUrl(options.url));
+  if (!match) {
+    issues.push(
+      issue(
+        ISSUE_CODES.WEBHOOK_NOT_FOUND,
+        "error",
+        `No webhook registered for URL ${options.url} on store ${options.storeId}.`,
+        {
+          suggestedFix: "Register the webhook in Lemon Squeezy (Settings \u2192 Webhooks) and subscribe to the recommended events.",
+          context: { storeId: String(options.storeId), url: options.url }
+        }
+      )
+    );
+    return buildResult("webhook", mode, issues);
+  }
+  const subscribed = new Set(match.attributes.events);
+  const missingRecommended = RECOMMENDED_WEBHOOK_EVENTS.filter((event) => !subscribed.has(event));
+  const missingOptional = OPTIONAL_WEBHOOK_EVENTS.filter((event) => !subscribed.has(event));
+  if (missingRecommended.length > 0) {
+    issues.push(
+      issue(
+        ISSUE_CODES.WEBHOOK_EVENTS_MISSING,
+        "error",
+        `Webhook is missing recommended events: ${missingRecommended.join(", ")}.`,
+        {
+          suggestedFix: "Subscribe to all recommended events so the integration survives plan changes and refunds.",
+          context: { missing: missingRecommended.join(",") }
+        }
+      )
+    );
+  }
+  if (missingOptional.length > 0) {
+    issues.push(
+      issue(
+        ISSUE_CODES.WEBHOOK_OPTIONAL_EVENTS,
+        "info",
+        `Optional events not subscribed: ${missingOptional.join(", ")}.`,
+        { context: { missing: missingOptional.join(",") } }
+      )
+    );
+  }
+  return buildResult("webhook", mode, issues, match.attributes);
+}
+function normalizeUrl(raw) {
+  return raw.replace(/\/+$/, "").toLowerCase();
+}
+
+// src/validate/doctor.ts
+async function doctor(http, mode, options = {}) {
+  const results = [];
+  const connection = await validateConnection(http, mode);
+  results.push(connection);
+  if (!connection.ok) {
+    return { ok: false, mode, results };
+  }
+  if (options.storeId !== void 0) {
+    results.push(await validateStore(http, mode, options.storeId));
+  }
+  if (options.productId !== void 0) {
+    results.push(
+      await validateProduct(http, mode, {
+        productId: options.productId,
+        expectedStoreId: options.storeId
+      })
+    );
+  }
+  if (options.storeId !== void 0 && options.webhookUrl !== void 0) {
+    results.push(
+      await validateWebhook(http, mode, {
+        storeId: options.storeId,
+        url: options.webhookUrl
+      })
+    );
+  }
+  const ok = results.every((result) => result.ok);
+  return { ok, mode, results };
+}
+
+// src/createFreshSqueezy.ts
+function createFreshSqueezy(config = {}) {
+  const resolved = resolveConfig(config);
+  const http = new HttpClient(resolved);
+  return {
+    mode: resolved.mode,
+    request: (options) => http.request(options),
+    validateConnection: () => validateConnection(http, resolved.mode),
+    validateStore: (storeId) => validateStore(http, resolved.mode, storeId),
+    validateProduct: (options) => validateProduct(http, resolved.mode, options),
+    validateWebhook: (options) => validateWebhook(http, resolved.mode, options),
+    doctor: (options) => doctor(http, resolved.mode, {
+      storeId: options?.storeId ?? resolved.storeId,
+      productId: options?.productId,
+      webhookUrl: options?.webhookUrl
+    })
+  };
+}
+export {
+  ACKNOWLEDGED_CHANGELOG_ENTRIES,
+  ENV_KEYS,
+  FreshSqueezyError,
+  ISSUE_CODES,
+  OPTIONAL_WEBHOOK_EVENTS,
+  RECOMMENDED_WEBHOOK_EVENTS,
+  SUPPORTED_RESOURCES,
+  buildResult,
+  createFreshSqueezy,
+  doctor,
+  getAuthenticatedUser,
+  getProduct,
+  getStore,
+  isOk,
+  issue,
+  listProducts,
+  listStores,
+  listVariantsForProduct,
+  listWebhooksForStore,
+  resolveConfig,
+  userResource,
+  validateConnection,
+  validateProduct,
+  validateWebhook
+};
+//# sourceMappingURL=index.js.map