fresh-squeezy 0.1.7 → 0.1.8

package/dist/cli.js

@@ -4,6 +4,155 @@
 import { Command } from "commander";
 import dotenv from "dotenv";
 
+// src/cli/commands/augment.ts
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+async function runAugmentCommand(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const outPath = resolve(cwd, options.out ?? "lemonsqueezy.augment.d.ts");
+  try {
+    const flavour = await detectFlavour(cwd, options.force ?? false);
+    const contents = renderAugmentationFile(flavour);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, contents, "utf8");
+    process.stdout.write(`fresh-squeezy: wrote ${outPath} (${flavour}).
+`);
+    if (flavour === "with-sdk") {
+      process.stdout.write(
+        `Use it via: import type { LemonSqueezyAugmented } from "./lemonsqueezy.augment";
+`
+      );
+    } else {
+      process.stdout.write(
+        `Use it via: import type { WithLatestLemonSqueezyFields } from "./lemonsqueezy.augment";
+`
+      );
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`fresh-squeezy: ${message}
+`);
+    return 2;
+  }
+}
+async function detectFlavour(cwd, force) {
+  if (force) return "generic";
+  const pkgPath = resolve(cwd, "package.json");
+  if (!existsSync(pkgPath)) return "generic";
+  const raw = await readFile(pkgPath, "utf8");
+  const pkg = JSON.parse(raw);
+  const deps = {
+    ...pkg.dependencies ?? {},
+    ...pkg.devDependencies ?? {},
+    ...pkg.peerDependencies ?? {}
+  };
+  return "@lemonsqueezy/lemonsqueezy.js" in deps ? "with-sdk" : "generic";
+}
+function renderAugmentationFile(flavour) {
+  const header = `/**
+ * Generated by \`fresh-squeezy types:augment\` \u2014 re-run after upgrading
+ * fresh-squeezy to refresh the field set.
+ *
+ * Why this file exists: the live Lemon Squeezy API has acquired fields
+ * since the SDK / hand-rolled types in this repo were last updated
+ * (e.g. \`payment_processor\`, \`tax_inclusive\`, \`refunded_amount*\`,
+ * \`setup_fee*\`, \`unit_price_decimal\`). fresh-squeezy tracks them in its
+ * manifest; this file makes them appear on your existing resource types
+ * so you don't hand-roll the additions.
+ *
+ * To wire it in:
+ *   1. Make sure your tsconfig.json's "include" covers this file (most
+ *      do by default if it's in the project root or under "src").
+ *   2. Import the augmented type from this file instead of the raw SDK
+ *      type \u2014 see the example at the bottom of this file.
+ */
+
+`;
+  if (flavour === "with-sdk") {
+    return header + `import type {
+  Subscription,
+  Order,
+  Variant,
+  Price,
+} from "@lemonsqueezy/lemonsqueezy.js";
+import type {
+  LatestSubscriptionFields,
+  LatestOrderFields,
+  LatestVariantFields,
+  LatestPriceFields,
+} from "fresh-squeezy";
+
+/**
+ * One-stop reference for resources fresh-squeezy has wider knowledge of
+ * than the official SDK. The shape mirrors the SDK's response envelope
+ * (\`{ data: { attributes: ... } }\`) \u2014 only the inner attributes are
+ * widened.
+ */
+export interface LemonSqueezyAugmented {
+  subscription: AugmentResponse<Subscription, LatestSubscriptionFields>;
+  order: AugmentResponse<Order, LatestOrderFields>;
+  variant: AugmentResponse<Variant, LatestVariantFields>;
+  price: AugmentResponse<Price, LatestPriceFields>;
+}
+
+/**
+ * Helper that walks the official SDK's response envelope and intersects
+ * the inner \`attributes\` record with the supplied field set.
+ */
+type AugmentResponse<T, Fields> = T extends {
+  data: infer Data;
+}
+  ? Data extends { attributes: infer Attrs }
+    ? Omit<T, "data"> & {
+        data: Omit<Data, "attributes"> & { attributes: Attrs & Fields };
+      }
+    : T
+  : T;
+
+/* Example:
+ *
+ * import type { LemonSqueezyAugmented } from "./lemonsqueezy.augment";
+ *
+ * function describe(sub: LemonSqueezyAugmented["subscription"]) {
+ *   const attrs = sub.data.attributes;
+ *   console.log(attrs.payment_processor); // \u2190 typed, no manual extension
+ *   console.log(attrs.urls?.update_customer_portal);
+ * }
+ */
+`;
+  }
+  return header + `import type {
+  WithLatestLemonSqueezyFields,
+  LatestSubscriptionFields,
+  LatestOrderFields,
+  LatestVariantFields,
+  LatestPriceFields,
+} from "fresh-squeezy";
+
+export type {
+  WithLatestLemonSqueezyFields,
+  LatestSubscriptionFields,
+  LatestOrderFields,
+  LatestVariantFields,
+  LatestPriceFields,
+};
+
+/* Example with a hand-rolled or third-party type:
+ *
+ * import type { WithLatestLemonSqueezyFields } from "./lemonsqueezy.augment";
+ *
+ * type MySubscription = WithLatestLemonSqueezyFields<MyExistingSubscription, "subscription">;
+ *
+ * function describe(sub: MySubscription) {
+ *   console.log(sub.payment_processor);   // typed
+ *   console.log(sub.tax_inclusive);       // typed
+ * }
+ */
+`;
+}
+
 // src/core/errors.ts
 var FreshSqueezyError = class _FreshSqueezyError extends Error {
   code;
@@ -97,14 +246,41 @@ var HttpClient = class {
     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.
+   * Fetch a single page of a JSON:API collection. Most callers want
+   * `paginate()` instead — this method is kept for one-shot lookups where
+   * the caller knows the result fits in a single page.
    */
   async getCollection(path2, query) {
     const doc = await this.request({ path: path2, query });
     return doc.data;
   }
+  /**
+   * Walk a JSON:API collection across every page and concatenate the
+   * results. Lemon Squeezy returns 25 items per page by default; without
+   * pagination, validators silently miss anything past the first page (e.g.
+   * `validateWebhook` on a store with 26+ webhooks would falsely report
+   * `WEBHOOK_NOT_FOUND` for any webhook on page 2).
+   *
+   * Stops as soon as `meta.page.lastPage` is reached. Falls back to a
+   * single-page fetch if the API does not surface page metadata.
+   *
+   * Caller-supplied `page[number]` is honored as the starting page; we
+   * advance from there. `page[size]` is left untouched so callers can tune
+   * batch size (max 100 per Lemon Squeezy docs).
+   */
+  async paginate(path2, query) {
+    const startPage = Number(query?.["page[number]"] ?? 1);
+    const all = [];
+    let pageNumber = startPage;
+    while (true) {
+      const pagedQuery = { ...query ?? {}, "page[number]": pageNumber };
+      const doc = await this.request({ path: path2, query: pagedQuery });
+      all.push(...doc.data);
+      const lastPage = doc.meta?.page?.lastPage;
+      if (lastPage === void 0 || pageNumber >= lastPage) return all;
+      pageNumber += 1;
+    }
+  }
   buildUrl(path2, query) {
     const url = new URL(path2, this.config.baseUrl);
     if (query) {
@@ -144,12 +320,19 @@ async function getAuthenticatedUser(http) {
   return http.request({ path: "/v1/users/me" });
 }
 
+// src/core/mode.ts
+function resolveActualMode(testMode) {
+  if (testMode === true) return "test";
+  if (testMode === false) return "live";
+  return void 0;
+}
+
 // src/resources/stores.ts
 async function getStore(http, storeId) {
   return http.getResource(`/v1/stores/${storeId}`);
 }
 async function listStores(http) {
-  return http.getCollection("/v1/stores");
+  return http.paginate("/v1/stores");
 }
 
 // src/validate/rules.ts
@@ -209,6 +392,72 @@ function buildResult(name, mode, issues, resource) {
   return result;
 }
 
+// src/validate/probe.ts
+function mapErrorToIssue(err, mapping = {}) {
+  if (err instanceof FreshSqueezyError) {
+    if (mapping.unauthorized && (err.status === 401 || err.code === "UNAUTHORIZED")) {
+      return issue(mapping.unauthorized.code, "error", mapping.unauthorized.message, {
+        ...mapping.unauthorized.suggestedFix !== void 0 ? { suggestedFix: mapping.unauthorized.suggestedFix } : {},
+        context: { status: err.status ?? null }
+      });
+    }
+    if (mapping.notFound && err.status === 404) {
+      return issue(mapping.notFound.code, "error", mapping.notFound.message, {
+        ...mapping.notFound.suggestedFix !== void 0 ? { suggestedFix: mapping.notFound.suggestedFix } : {},
+        ...mapping.notFound.context !== void 0 ? { context: mapping.notFound.context } : {}
+      });
+    }
+    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);
+}
+async function probeFetch(fetcher, options) {
+  try {
+    return { ok: true, resource: await fetcher() };
+  } catch (err) {
+    return {
+      ok: false,
+      issue: mapErrorToIssue(err, {
+        notFound: {
+          code: options.notFoundCode,
+          message: options.notFoundMessage,
+          ...options.notFoundFix !== void 0 ? { suggestedFix: options.notFoundFix } : {},
+          ...options.notFoundContext !== void 0 ? { context: options.notFoundContext } : {}
+        }
+      })
+    };
+  }
+}
+function checkStoreOwnership(check) {
+  const expected = String(check.expectedStoreId);
+  const actual = String(check.actualStoreId);
+  if (expected === actual) return null;
+  const context = {
+    expectedStoreId: expected,
+    actualStoreId: actual,
+    ...check.extraContext ?? {}
+  };
+  return issue(
+    check.code,
+    "error",
+    `${check.label} belongs to store ${actual}, expected ${expected}.`,
+    {
+      ...check.suggestedFix !== void 0 ? { suggestedFix: check.suggestedFix } : {},
+      context
+    }
+  );
+}
+
 // src/validate/connection.ts
 async function validateConnection(http, mode) {
   const issues = [];
@@ -248,67 +497,33 @@ async function validateConnection(http, mode) {
     }
     return buildResult("connection", mode, issues, summary);
   } catch (err) {
-    issues.push(toConnectionIssue(err));
+    issues.push(
+      mapErrorToIssue(err, {
+        unauthorized: {
+          code: ISSUE_CODES.AUTH_FAILED,
+          message: "API key rejected by Lemon Squeezy.",
+          suggestedFix: "Regenerate the key at https://app.lemonsqueezy.com/settings/api."
+        }
+      })
+    );
     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));
+  const fetched = await probeFetch(() => getStore(http, storeId), {
+    notFoundCode: ISSUE_CODES.STORE_NOT_FOUND,
+    notFoundMessage: `Store ${storeId} not found with the current API key.`,
+    notFoundFix: "Check the store ID and confirm the API key belongs to the account that owns it.",
+    notFoundContext: { storeId: String(storeId) }
+  });
+  if (!fetched.ok) {
+    issues.push(fetched.issue);
     return buildResult("store", mode, issues);
   }
+  return buildResult("store", mode, issues, fetched.resource.attributes);
 }
 
 // src/resources/products.ts
@@ -321,7 +536,7 @@ async function getVariant(http, variantId) {
   return http.getResource(`/v1/variants/${variantId}`);
 }
 async function listVariantsForProduct(http, productId) {
-  return http.getCollection("/v1/variants", {
+  return http.paginate("/v1/variants", {
     "filter[product_id]": String(productId)
   });
 }
@@ -329,45 +544,26 @@ async function listVariantsForProduct(http, 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));
+  const fetched = await probeFetch(() => getProduct(http, options.productId), {
+    notFoundCode: ISSUE_CODES.PRODUCT_NOT_FOUND,
+    notFoundMessage: `Product ${options.productId} not found.`,
+    notFoundFix: "Verify the product ID in the Lemon Squeezy dashboard.",
+    notFoundContext: { productId: String(options.productId) }
+  });
+  if (!fetched.ok) {
+    issues.push(fetched.issue);
     return buildResult("product", mode, issues);
   }
-  const attrs = product.attributes;
+  const attrs = fetched.resource.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 }
-          }
-        )
-      );
-    }
+    const mismatch = checkStoreOwnership({
+      expectedStoreId: options.expectedStoreId,
+      actualStoreId: attrs.store_id,
+      code: ISSUE_CODES.PRODUCT_WRONG_STORE,
+      label: "Product",
+      suggestedFix: "Either use the correct store ID or the correct product ID \u2014 IDs should not cross stores."
+    });
+    if (mismatch) issues.push(mismatch);
   }
   if (attrs.status !== "published") {
     issues.push(
@@ -420,9 +616,17 @@ async function validateProduct(http, mode, options) {
   return buildResult("product", mode, issues, attrs);
 }
 
+// src/core/equality.ts
+function sameWebhookUrl(a, b) {
+  return normalizeWebhookUrl(a) === normalizeWebhookUrl(b);
+}
+function normalizeWebhookUrl(raw) {
+  return raw.replace(/\/+$/, "").toLowerCase();
+}
+
 // src/resources/webhooks.ts
 async function listWebhooksForStore(http, storeId) {
-  return http.getCollection("/v1/webhooks", {
+  return http.paginate("/v1/webhooks", {
     "filter[store_id]": String(storeId)
   });
 }
@@ -465,7 +669,7 @@ async function validateWebhook(http, mode, options) {
     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));
+  const match = webhooks.find((webhook) => sameWebhookUrl(webhook.attributes.url, options.url));
   if (!match) {
     issues.push(
       issue(
@@ -508,9 +712,6 @@ async function validateWebhook(http, mode, options) {
   }
   return buildResult("webhook", mode, issues, match.attributes);
 }
-function normalizeUrl(raw) {
-  return raw.replace(/\/+$/, "").toLowerCase();
-}
 
 // src/resources/discounts.ts
 async function getDiscount(http, discountId) {
@@ -520,39 +721,25 @@ async function getDiscount(http, discountId) {
 // src/validate/discount.ts
 async function validateDiscount(http, mode, options) {
   const issues = [];
-  let discount;
-  try {
-    discount = await getDiscount(http, options.discountId);
-  } catch (err) {
-    if (err instanceof FreshSqueezyError && err.status === 404) {
-      issues.push(
-        issue(ISSUE_CODES.DISCOUNT_NOT_FOUND, "error", `Discount ${options.discountId} not found.`, {
-          suggestedFix: "Verify the discount ID in the Lemon Squeezy dashboard.",
-          context: { discountId: String(options.discountId) }
-        })
-      );
-      return buildResult("discount", mode, issues);
-    }
-    const message = err instanceof Error ? err.message : "Unknown error";
-    issues.push(issue(ISSUE_CODES.UNKNOWN, "error", message));
+  const fetched = await probeFetch(() => getDiscount(http, options.discountId), {
+    notFoundCode: ISSUE_CODES.DISCOUNT_NOT_FOUND,
+    notFoundMessage: `Discount ${options.discountId} not found.`,
+    notFoundFix: "Verify the discount ID in the Lemon Squeezy dashboard.",
+    notFoundContext: { discountId: String(options.discountId) }
+  });
+  if (!fetched.ok) {
+    issues.push(fetched.issue);
     return buildResult("discount", mode, issues);
   }
-  const attrs = discount.attributes;
-  const expectedStore = String(options.storeId);
-  const actualStore = String(attrs.store_id);
-  if (expectedStore !== actualStore) {
-    issues.push(
-      issue(
-        ISSUE_CODES.DISCOUNT_STORE_MISMATCH,
-        "error",
-        `Discount belongs to store ${actualStore}, expected ${expectedStore}.`,
-        {
-          suggestedFix: "Use the correct store ID or discount ID \u2014 discounts should not cross stores.",
-          context: { expectedStoreId: expectedStore, actualStoreId: actualStore }
-        }
-      )
-    );
-  }
+  const attrs = fetched.resource.attributes;
+  const mismatch = checkStoreOwnership({
+    expectedStoreId: options.storeId,
+    actualStoreId: attrs.store_id,
+    code: ISSUE_CODES.DISCOUNT_STORE_MISMATCH,
+    label: "Discount",
+    suggestedFix: "Use the correct store ID or discount ID \u2014 discounts should not cross stores."
+  });
+  if (mismatch) issues.push(mismatch);
   if (attrs.status === "draft") {
     issues.push(
       issue(
@@ -642,44 +829,25 @@ async function getLicenseKey(http, licenseKeyId) {
 // src/validate/licenseKey.ts
 async function validateLicenseKey(http, mode, options) {
   const issues = [];
-  let licenseKey;
-  try {
-    licenseKey = await getLicenseKey(http, options.licenseKeyId);
-  } catch (err) {
-    if (err instanceof FreshSqueezyError && err.status === 404) {
-      issues.push(
-        issue(
-          ISSUE_CODES.LICENSE_KEY_NOT_FOUND,
-          "error",
-          `License key ${options.licenseKeyId} not found.`,
-          {
-            suggestedFix: "Verify the license key ID in the Lemon Squeezy dashboard.",
-            context: { licenseKeyId: String(options.licenseKeyId) }
-          }
-        )
-      );
-      return buildResult("licenseKey", mode, issues);
-    }
-    const message = err instanceof Error ? err.message : "Unknown error";
-    issues.push(issue(ISSUE_CODES.UNKNOWN, "error", message));
+  const fetched = await probeFetch(() => getLicenseKey(http, options.licenseKeyId), {
+    notFoundCode: ISSUE_CODES.LICENSE_KEY_NOT_FOUND,
+    notFoundMessage: `License key ${options.licenseKeyId} not found.`,
+    notFoundFix: "Verify the license key ID in the Lemon Squeezy dashboard.",
+    notFoundContext: { licenseKeyId: String(options.licenseKeyId) }
+  });
+  if (!fetched.ok) {
+    issues.push(fetched.issue);
     return buildResult("licenseKey", mode, issues);
   }
-  const attrs = licenseKey.attributes;
-  const expectedStore = String(options.storeId);
-  const actualStore = String(attrs.store_id);
-  if (expectedStore !== actualStore) {
-    issues.push(
-      issue(
-        ISSUE_CODES.LICENSE_KEY_STORE_MISMATCH,
-        "error",
-        `License key belongs to store ${actualStore}, expected ${expectedStore}.`,
-        {
-          suggestedFix: "Use the correct store ID or license key ID \u2014 keys should not cross stores.",
-          context: { expectedStoreId: expectedStore, actualStoreId: actualStore }
-        }
-      )
-    );
-  }
+  const attrs = fetched.resource.attributes;
+  const mismatch = checkStoreOwnership({
+    expectedStoreId: options.storeId,
+    actualStoreId: attrs.store_id,
+    code: ISSUE_CODES.LICENSE_KEY_STORE_MISMATCH,
+    label: "License key",
+    suggestedFix: "Use the correct store ID or license key ID \u2014 keys should not cross stores."
+  });
+  if (mismatch) issues.push(mismatch);
   if (attrs.disabled) {
     issues.push(
       issue(
@@ -730,28 +898,20 @@ async function validateLicenseKey(http, mode, options) {
 var VALID_INTERVALS = /* @__PURE__ */ new Set(["day", "week", "month", "year"]);
 async function validateSubscriptionPlan(http, mode, options) {
   const issues = [];
-  let variant;
-  try {
-    variant = await getVariant(http, options.variantId);
-  } catch (err) {
-    if (err instanceof FreshSqueezyError && err.status === 404) {
-      issues.push(
-        issue(
-          ISSUE_CODES.PLAN_VARIANT_NOT_FOUND,
-          "error",
-          `Variant ${options.variantId} not found.`,
-          {
-            suggestedFix: "Verify the variant ID in the Lemon Squeezy dashboard.",
-            context: { variantId: String(options.variantId) }
-          }
-        )
-      );
-      return buildResult("subscriptionPlan", mode, issues);
+  const fetched = await probeFetch(
+    () => getVariant(http, options.variantId),
+    {
+      notFoundCode: ISSUE_CODES.PLAN_VARIANT_NOT_FOUND,
+      notFoundMessage: `Variant ${options.variantId} not found.`,
+      notFoundFix: "Verify the variant ID in the Lemon Squeezy dashboard.",
+      notFoundContext: { variantId: String(options.variantId) }
     }
-    const message = err instanceof Error ? err.message : "Unknown error";
-    issues.push(issue(ISSUE_CODES.UNKNOWN, "error", message));
+  );
+  if (!fetched.ok) {
+    issues.push(fetched.issue);
     return buildResult("subscriptionPlan", mode, issues);
   }
+  const variant = fetched.resource;
   const attrs = variant.attributes;
   if (!attrs.is_subscription) {
     issues.push(
@@ -836,21 +996,15 @@ async function validateSubscriptionPlan(http, mode, options) {
   }
   try {
     const product = await getProduct(http, attrs.product_id);
-    const expectedStore = String(options.storeId);
-    const actualStore = String(product.attributes.store_id);
-    if (expectedStore !== actualStore) {
-      issues.push(
-        issue(
-          ISSUE_CODES.PLAN_STORE_MISMATCH,
-          "error",
-          `Subscription variant belongs to store ${actualStore} (via product ${attrs.product_id}), expected ${expectedStore}.`,
-          {
-            suggestedFix: "Use the correct store ID or variant ID \u2014 plans should not cross stores.",
-            context: { expectedStoreId: expectedStore, actualStoreId: actualStore, productId: String(attrs.product_id) }
-          }
-        )
-      );
-    }
+    const mismatch = checkStoreOwnership({
+      expectedStoreId: options.storeId,
+      actualStoreId: product.attributes.store_id,
+      code: ISSUE_CODES.PLAN_STORE_MISMATCH,
+      label: `Subscription variant (via product ${attrs.product_id})`,
+      suggestedFix: "Use the correct store ID or variant ID \u2014 plans should not cross stores.",
+      extraContext: { productId: String(attrs.product_id) }
+    });
+    if (mismatch) issues.push(mismatch);
   } catch {
   }
   const summary = {
@@ -865,19 +1019,29 @@ async function validateSubscriptionPlan(http, mode, options) {
 }
 
 // src/validate/doctor.ts
-async function doctor(http, mode, options = {}) {
+var DEFAULT_VALIDATORS = {
+  connection: validateConnection,
+  store: validateStore,
+  product: validateProduct,
+  webhook: validateWebhook,
+  discount: validateDiscount,
+  licenseKey: validateLicenseKey,
+  subscriptionPlan: validateSubscriptionPlan
+};
+async function doctor(http, mode, options = {}, validators = DEFAULT_VALIDATORS) {
+  assertOptionsCoherent(options);
   const results = [];
-  const connection = await validateConnection(http, mode);
+  const connection = await validators.connection(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));
+    results.push(await validators.store(http, mode, options.storeId));
   }
   if (options.productId !== void 0) {
     results.push(
-      await validateProduct(http, mode, {
+      await validators.product(http, mode, {
         productId: options.productId,
         expectedStoreId: options.storeId
       })
@@ -885,7 +1049,7 @@ async function doctor(http, mode, options = {}) {
   }
   if (options.storeId !== void 0 && options.webhookUrl !== void 0) {
     results.push(
-      await validateWebhook(http, mode, {
+      await validators.webhook(http, mode, {
         storeId: options.storeId,
         url: options.webhookUrl
       })
@@ -893,7 +1057,7 @@ async function doctor(http, mode, options = {}) {
   }
   if (options.storeId !== void 0 && options.discountId !== void 0) {
     results.push(
-      await validateDiscount(http, mode, {
+      await validators.discount(http, mode, {
         storeId: options.storeId,
         discountId: options.discountId
       })
@@ -901,7 +1065,7 @@ async function doctor(http, mode, options = {}) {
   }
   if (options.storeId !== void 0 && options.licenseKeyId !== void 0) {
     results.push(
-      await validateLicenseKey(http, mode, {
+      await validators.licenseKey(http, mode, {
         storeId: options.storeId,
         licenseKeyId: options.licenseKeyId
       })
@@ -909,7 +1073,7 @@ async function doctor(http, mode, options = {}) {
   }
   if (options.storeId !== void 0 && options.variantId !== void 0) {
     results.push(
-      await validateSubscriptionPlan(http, mode, {
+      await validators.subscriptionPlan(http, mode, {
         storeId: options.storeId,
         variantId: options.variantId
       })
@@ -918,6 +1082,19 @@ async function doctor(http, mode, options = {}) {
   const ok = results.every((result) => result.ok);
   return { ok, mode, results };
 }
+function assertOptionsCoherent(options) {
+  if (options.storeId !== void 0) return;
+  const dependent = [];
+  if (options.webhookUrl !== void 0) dependent.push("webhookUrl");
+  if (options.discountId !== void 0) dependent.push("discountId");
+  if (options.licenseKeyId !== void 0) dependent.push("licenseKeyId");
+  if (options.variantId !== void 0) dependent.push("variantId");
+  if (dependent.length === 0) return;
+  throw new FreshSqueezyError({
+    code: "DOCTOR_OPTIONS_INVALID",
+    message: `doctor() received ${dependent.join(", ")} without storeId. These validators cannot run without a store; pass \`storeId\` or remove the dependent options.`
+  });
+}
 
 // src/createFreshSqueezy.ts
 function createFreshSqueezy(config = {}) {
@@ -1363,6 +1540,13 @@ program.command("init").description("Interactive setup: ask for credentials, pic
   const code = await runInitCommand({ envFile: opts.envFile });
   process.exit(code);
 });
+var types = program.command("types").description("Type-augmentation utilities for the official Lemon Squeezy SDK and hand-rolled types");
+types.command("augment").description(
+  "Generate a .d.ts that intersects your Lemon Squeezy resource types with fields fresh-squeezy already tracks (e.g. payment_processor, tax_inclusive, refunded_amount*)."
+).option("--out <path>", "Output path (default: lemonsqueezy.augment.d.ts in CWD)").option("--force", "Emit the generic file even when @lemonsqueezy/lemonsqueezy.js is detected").action(async (opts) => {
+  const code = await runAugmentCommand({ out: opts.out, force: Boolean(opts.force) });
+  process.exit(code);
+});
 program.parseAsync(process.argv).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
   process.stderr.write(`fresh-squeezy: ${message}