@sense-apps/mantle 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,14 @@
-# @mantlekit/sdk
+# @sense-apps/mantle
 
-Backend-only client your Shopify app uses to talk to your Mantlekit deployment. It deliberately mirrors Mantle's `@heymantle/client` (`MantleClient`) — same constructor shape, method names, and `customer.plan` / `customer.subscription` / `customer.features` nesting — so moving an app off Mantle is close to a find-and-replace.
+Backend-only client your Shopify app uses to talk to your Mantlekit deployment. Response shapes (`Customer` / `Subscription` / `Plan` / `Feature`) are aligned field-for-field with Mantle's `@heymantle/client@1.1.51` for everything Mantlekit supports — same nesting, same field names, same helper semantics — so Mantle-era code like `customer.subscription?.plan?.features["unlimited_bars"]?.value` ports unchanged.
 
 **Server-side only.** Your frontend never talks to Mantlekit directly; it talks to your own backend, which uses this client and relays whatever your frontend needs.
 
 ## Install
 
 ```bash
-bun add @mantlekit/sdk
-# or: npm install @mantlekit/sdk
+bun add @sense-apps/mantle
+# or: npm install @sense-apps/mantle
 ```
 
 ## Configure
@@ -23,7 +23,7 @@ MANTLEKIT_API_KEY=mk_...   # per-app API key, created in the Mantlekit dashboard
 Then construct with no arguments:
 
 ```ts
-import { MantleKitClient } from "@mantlekit/sdk";
+import { MantleKitClient } from "@sense-apps/mantle";
 
 const admin = new MantleKitClient(); // reads MANTLEKIT_URL + MANTLEKIT_API_KEY
 ```
@@ -66,52 +66,84 @@ const { shopId, apiToken } = await admin.identify({
 const client = new MantleKitClient({ customerApiToken: shop.mantlekitToken });
 ```
 
-### 3. Pricing page
+### 3. Read the customer — Mantle's exact nesting
+
+```ts
+const customer = await client.getCustomer();
+const subscription = customer?.subscription || null;
+
+if (subscription?.plan) {
+  SetPlanMetafields(shopifyClient, subscription.plan); // full Plan: total, interval, features, …
+}
+
+const isPremiumUser = subscription?.plan?.features["unlimited_bars"]?.value === true;
+const maxBarViews = (subscription?.plan?.features["bar_views"]?.value as number) || 2500;
+```
+
+`Customer` also carries `plans` (the eligible-plan list, same as `getPlans()`), `features` (resolved for the shop — falls back to each feature's default when there's no subscription), and `billingStatus` (`"none" | "active" | "trialing" | "canceled" | "frozen"`).
+
+### 4. Pricing page
 
 ```ts
 const plans = await client.getPlans();
-// ResolvedPlan[]: planId, name, amount (string — money is never a float),
-// currencyCode, trialDays, viaOverride, features
+// Mantle Plan shape: id, name, total, subtotal, interval ("EVERY_30_DAYS" | "ANNUAL" | "QUARTERLY"),
+// trialDays, currencyCode, features, featuresOrder, discounts, autoAppliedDiscount, flexBilling, …
 ```
 
-Eligibility (tag rules, per-shop overrides) is resolved server-side by Mantlekit — the list you get back is exactly what this shop may buy.
+Eligibility (tag rules, per-shop price/trial overrides) is resolved server-side — the list is exactly what this shop may buy, with override pricing already applied. Money fields (`total`, `subtotal`) are numbers only because that is Mantle's wire shape — treat them as display values.
 
-### 4. Subscribe / upgrade
+**Discounts** work like Mantle's: created in the Mantlekit dashboard as a percentage (`percentage: 20` = 20%) or fixed amount off, optionally limited to specific plans, for a number of billing intervals (or forever / until a date), and auto-applied to shops by tag. When one auto-applies, `plan.autoAppliedDiscount` is set and `plan.total` is already the discounted price, with `plan.subtotal` the original — render a slashed price:
 
 ```ts
-const { confirmationUrl } = await client.subscribe({
+if (plan.autoAppliedDiscount) {
+  render(`~~$${plan.subtotal}~~ $${plan.total}/mo — ${plan.autoAppliedDiscount.percentage}% off`);
+}
+```
+
+The same discount is forwarded to Shopify at subscribe time (on the recurring line item), so the approval screen and the real charge match what you displayed. Flex-billing plans never get auto-applied discounts (Shopify's discount input can't reach usage lines).
+
+### 5. Subscribe / upgrade
+
+```ts
+const subscription = await client.subscribe({
   planId,
   returnUrl: `https://your-app.com/billing/confirm?shop=${shop.domain}`,
 });
-// redirect the merchant's browser to confirmationUrl (Shopify approval screen)
+// redirect the merchant's browser to Shopify's approval screen:
+redirect(subscription.confirmationUrl!);
 ```
 
-The subscription only becomes active after the merchant approves and Shopify's webhook lands back in Mantlekit — don't grant features on redirect alone; check `getCustomer()`.
+The subscription only becomes active after the merchant approves and Shopify confirms — don't grant features on redirect alone; check `getCustomer()`.
 
-### 5. Gate features
+### 6. Gate features
 
 ```ts
-const customer = await client.getCustomer();
-// { id, myshopifyDomain, plan, subscription: { status, trialEndsAt, ... }, features }
+if (await client.isFeatureEnabled({ featureKey: "unlimited_bars" })) { ... }
+
+// limit features evaluate as `count < limit`, -1 = unlimited — Mantle's semantics:
+const canAddBar = await client.isFeatureEnabled({ featureKey: "bars", count: currentBarCount });
 
-if (await client.isFeatureEnabled("advanced_reports")) { ... }
-const maxSeats = await client.limitForFeature("team_seats"); // number | null
+const maxSeats = await client.limitForFeature({ featureKey: "team_seats" }); // -1 if not a limit feature
 ```
 
-`isFeatureEnabled` / `limitForFeature` each call `getCustomer()` under the hood — if you need several flags in one request, call `getCustomer()` once and read `customer.features` yourself.
+Both helpers also accept a bare string key. Each one calls `getCustomer()` under the hood — if you need several flags in one request, call `getCustomer()` once and read `customer.features` yourself.
 
-### 6. Cancel
+### 7. Cancel
 
 ```ts
-await client.cancelSubscription();
+const cancelled = await client.cancelSubscription(); // resolves to the cancelled Subscription
 ```
 
+## What's intentionally empty
+
+Mantle features Mantlekit doesn't implement are emitted as empty values rather than omitted, so ported code never crashes on `.length`/`?.`: `subscription.lineItems`, `plan.discounts`, `customer.usage`, `customer.usageCredits`, `customer.reviews`, `customer.paymentMethod`, `customFields`. There are no client methods for Stripe billing, invoices, notifications, or checklists.
+
 ## Errors
 
 Every non-2xx response throws `MantleKitError` with `status` and, for validation failures, `userErrors: { field, message }[]`:
 
 ```ts
-import { MantleKitError } from "@mantlekit/sdk";
+import { MantleKitError } from "@sense-apps/mantle";
 
 try {
   await client.subscribe({ planId, returnUrl });

package/dist/client.d.ts

@@ -1,13 +1,16 @@
 /**
- * @mantlekit/sdk — BACKEND-ONLY client library a merchant's OWN Shopify app
- * uses to talk to a Mantlekit deployment, the same way `@heymantle/client`
+ * @sense-apps/mantle — BACKEND-ONLY client library a merchant's OWN Shopify
+ * app uses to talk to a Mantlekit deployment, the same way `@heymantle/client`
  * (MantleClient) talks to api.heymantle.com — except `baseUrl` points at
  * YOUR domain, since you own the whole stack (no third party in the loop).
- * Constructor shape, method names (`identify`, `getCustomer`, `getPlans`,
- * `isFeatureEnabled`, `limitForFeature`), and the `customer.features`/
- * `customer.plan`/`customer.subscription` nesting deliberately mirror
- * MantleClient (see appapi.heymantle.dev/docs/understanding-mantleclient)
- * so porting off Mantle is close to a drop-in swap.
+ *
+ * Response shapes (Customer / Subscription / Plan / Feature) are aligned
+ * field-for-field with @heymantle/client@1.1.51 for everything Mantlekit
+ * supports, so Mantle-era code like
+ * `customer.subscription?.plan?.features["unlimited_bars"]?.value` ports
+ * unchanged. Mantle features Mantlekit doesn't have (Stripe billing,
+ * invoices, notifications, checklists, usage metrics reporting) are emitted
+ * as empty values on the payloads and have no client methods.
  *
  * This package has NO frontend/browser usage — every call (including the
  * customerApiToken-scoped ones) is meant to run on your own server. Your
@@ -34,42 +37,130 @@
  *   3. Store `apiToken` against that shop in your own DB.
  *   4. On any request from YOUR frontend (e.g. your pricing page's data loader):
  *      const client = new MantleKitClient({ customerApiToken: storedApiToken });
- *      const plans = await client.getPlans();
- *      const customer = await client.getCustomer(); // { plan, subscription, features }
+ *      const customer = await client.getCustomer();
+ *      const plan = customer.subscription?.plan ?? null; // full Mantle-shaped Plan
  *      // ...then your backend returns whatever subset of this your frontend needs.
  */
-export type FeatureType = "boolean" | "limit" | "limit_overage" | "string";
-export interface ResolvedFeature {
+/** Mantle spells Mantlekit's "limit_overage" as "limit_with_overage"; the API maps it on the way out. */
+export type FeatureType = "boolean" | "limit" | "limit_with_overage" | "string";
+export interface Feature {
+    id: string;
     key: string;
     name: string;
     type: FeatureType;
+    description: string | null;
     value: boolean | number | string;
+    displayOrder: number;
 }
-export interface ResolvedPlan {
-    planId: string;
+export interface UsageCharge {
+    id: string;
+    amount: number;
+    type: "unit";
+    terms: string;
+    cappedAmount: number;
+}
+export interface Discount {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Set for fixed-amount discounts. */
+    amount?: number;
+    amountCurrencyCode?: string;
+    presentmentAmount?: number;
+    presentmentCurrencyCode?: string;
+    /** Set for percentage discounts — human number, 20 = 20%. */
+    percentage?: number;
+    /** How many billing intervals the discount lasts; absent = forever. */
+    durationLimitInIntervals?: number;
+    /** The plan price after this discount. */
+    discountedAmount: number;
+    presentmentDiscountedAmount: number;
+}
+export interface Plan {
+    id: string;
     name: string;
-    amount: string;
+    description: string | null;
+    availability: "public" | "customer" | "hidden";
+    type: "base";
     currencyCode: string;
+    presentmentAmount: number;
+    presentmentCurrencyCode: string;
+    /** Amount after discounts. Mantlekit has no discounts yet, so total === subtotal. */
+    total: number;
+    subtotal: number;
+    /** @deprecated Mantle deprecates this in favor of `subtotal`; kept for drop-in compat. */
+    amount: number;
+    public: boolean;
+    visible: boolean;
+    eligible: boolean;
     trialDays: number;
-    viaOverride: boolean;
-    features: Record<string, ResolvedFeature>;
+    interval: "EVERY_30_DAYS" | "ANNUAL" | "QUARTERLY";
+    features: Record<string, Feature>;
+    featuresOrder: string[];
+    usageCharges: UsageCharge[];
+    usageChargeCappedAmount?: number;
+    customFields: Record<string, unknown>;
+    /** Discounts attached to this plan (auto-apply and manual alike). */
+    discounts: Discount[];
+    /**
+     * The discount that auto-applies to this shop at subscribe time (targeted
+     * by plan/tags in the Mantlekit dashboard). `total` already reflects it;
+     * `subtotal` is the undiscounted price — render a slashed price when set.
+     */
+    autoAppliedDiscount?: Discount;
+    flexBilling: boolean;
+    flexBillingTerms: string | null;
+    autoUpgradeToPlanId: string | null;
+    createdAt?: string;
 }
-export interface ShopCustomer {
+export interface Subscription {
+    id: string;
+    plan: Plan;
+    lineItems: never[];
+    active: boolean;
+    activatedAt: string | null;
+    billingCycleAnchor: string | null;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialStartsAt: string | null;
+    trialExpiresAt: string | null;
+    cancelledAt: string | null;
+    createdAt: string | null;
+    features: Record<string, Feature>;
+    featuresOrder: string[];
+    usageCharges: UsageCharge[];
+    usageChargeCappedAmount?: number;
+    total: number;
+    subtotal: number;
+    presentmentTotal: number;
+    presentmentSubtotal: number;
+    /** Present on subscribe() responses — redirect the merchant's browser here. */
+    confirmationUrl?: string;
+    returnUrl?: string;
+    /** Mantlekit extra (not in Mantle's shape): raw status, e.g. "pending" | "active" | "cancelled". */
+    status: string;
+}
+export interface Customer {
     id: string;
-    myshopifyDomain: string;
     name: string | null;
     email: string | null;
+    test: boolean;
+    platform: "shopify";
+    platformId?: string;
+    myshopifyDomain: string;
     installedAt: string | null;
-    plan: {
-        id: string;
-        name: string;
-    } | null;
-    subscription: {
-        status: string;
-        trialEndsAt: string | null;
-        currentPeriodEnd: string | null;
-    };
-    features: Record<string, ResolvedFeature>;
+    trialStartsAt: string | null;
+    trialExpiresAt: string | null;
+    /** The plans this shop is eligible for — same list as getPlans(). */
+    plans: Plan[];
+    subscription: Subscription | null;
+    paymentMethod: null;
+    features: Record<string, Feature>;
+    usage: Record<string, never>;
+    customFields: Record<string, unknown>;
+    usageCredits: never[];
+    reviews: never[];
+    billingStatus: "none" | "active" | "trialing" | "canceled" | "frozen";
 }
 export interface IdentifyParams {
     myshopifyDomain: string;
@@ -91,14 +182,6 @@ export interface SubscribeParams {
     returnUrl: string;
     test?: boolean;
 }
-export interface SubscribeResult {
-    subscriptionId: string;
-    confirmationUrl: string;
-}
-export interface CancelSubscriptionResult {
-    id: string;
-    status: string;
-}
 export declare class MantleKitError extends Error {
     status: number;
     userErrors?: Array<{
@@ -136,17 +219,35 @@ export declare class MantleKitClient {
     /** Register (or re-sync) a shop after your app's own Shopify OAuth completes. Requires apiKey. */
     identify(params: IdentifyParams): Promise<IdentifyResult>;
     /** Plans this shop is eligible for — what your pricing page renders. Requires customerApiToken. */
-    getPlans(): Promise<ResolvedPlan[]>;
-    /** The shop's own record: { plan, subscription, features }. Requires customerApiToken. */
-    getCustomer(): Promise<ShopCustomer>;
-    /** Convenience wrapper over getCustomer().features — mirrors MantleClient.isFeatureEnabled(). */
-    isFeatureEnabled(featureKey: string): Promise<boolean>;
-    /** Convenience wrapper over getCustomer().features — mirrors MantleClient.limitForFeature(). */
-    limitForFeature(featureKey: string): Promise<number | null>;
-    /** Start checkout for a plan. Returns a confirmationUrl to redirect the merchant's browser to. Requires customerApiToken. */
-    subscribe(params: SubscribeParams): Promise<SubscribeResult>;
-    /** Cancel the shop's active subscription. Requires customerApiToken. */
-    cancelSubscription(): Promise<CancelSubscriptionResult>;
+    getPlans(): Promise<Plan[]>;
+    /** The shop's own record — Mantle Customer shape: { plans, subscription: { plan, ... }, features, billingStatus }. */
+    getCustomer(): Promise<Customer>;
+    /**
+     * Mirrors MantleClient.isFeatureEnabled({ featureKey, count }) — limits
+     * evaluate as `count < limit` (-1 = unlimited). A bare string argument is
+     * also accepted: isFeatureEnabled("unlimited_bars").
+     */
+    isFeatureEnabled(params: string | {
+        featureKey: string;
+        count?: number;
+    }): Promise<boolean>;
+    /**
+     * Mirrors MantleClient.limitForFeature({ featureKey }) — resolves to -1
+     * when the feature is missing or not a limit type, exactly like Mantle.
+     */
+    limitForFeature(params: string | {
+        featureKey: string;
+    }): Promise<number>;
+    /**
+     * Start checkout for a plan. Resolves to the pending Subscription —
+     * redirect the merchant's browser to `subscription.confirmationUrl`.
+     * Requires customerApiToken.
+     */
+    subscribe(params: SubscribeParams): Promise<Subscription>;
+    /** Cancel the shop's active subscription. Resolves to the cancelled Subscription. Requires customerApiToken. */
+    cancelSubscription(params?: {
+        cancelReason?: string;
+    }): Promise<Subscription>;
     private customerHeaders;
     private request;
 }

package/dist/client.js

@@ -1,13 +1,16 @@
 /**
- * @mantlekit/sdk — BACKEND-ONLY client library a merchant's OWN Shopify app
- * uses to talk to a Mantlekit deployment, the same way `@heymantle/client`
+ * @sense-apps/mantle — BACKEND-ONLY client library a merchant's OWN Shopify
+ * app uses to talk to a Mantlekit deployment, the same way `@heymantle/client`
  * (MantleClient) talks to api.heymantle.com — except `baseUrl` points at
  * YOUR domain, since you own the whole stack (no third party in the loop).
- * Constructor shape, method names (`identify`, `getCustomer`, `getPlans`,
- * `isFeatureEnabled`, `limitForFeature`), and the `customer.features`/
- * `customer.plan`/`customer.subscription` nesting deliberately mirror
- * MantleClient (see appapi.heymantle.dev/docs/understanding-mantleclient)
- * so porting off Mantle is close to a drop-in swap.
+ *
+ * Response shapes (Customer / Subscription / Plan / Feature) are aligned
+ * field-for-field with @heymantle/client@1.1.51 for everything Mantlekit
+ * supports, so Mantle-era code like
+ * `customer.subscription?.plan?.features["unlimited_bars"]?.value` ports
+ * unchanged. Mantle features Mantlekit doesn't have (Stripe billing,
+ * invoices, notifications, checklists, usage metrics reporting) are emitted
+ * as empty values on the payloads and have no client methods.
  *
  * This package has NO frontend/browser usage — every call (including the
  * customerApiToken-scoped ones) is meant to run on your own server. Your
@@ -34,8 +37,8 @@
  *   3. Store `apiToken` against that shop in your own DB.
  *   4. On any request from YOUR frontend (e.g. your pricing page's data loader):
  *      const client = new MantleKitClient({ customerApiToken: storedApiToken });
- *      const plans = await client.getPlans();
- *      const customer = await client.getCustomer(); // { plan, subscription, features }
+ *      const customer = await client.getCustomer();
+ *      const plan = customer.subscription?.plan ?? null; // full Mantle-shaped Plan
  *      // ...then your backend returns whatever subset of this your frontend needs.
  */
 export class MantleKitError extends Error {
@@ -49,6 +52,22 @@ export class MantleKitError extends Error {
     }
 }
 const env = (key) => typeof process !== "undefined" ? process.env?.[key] : undefined;
+/**
+ * Mirrors MantleClient's private evaluateFeature(): booleans by value,
+ * limits by `count < value` with -1 meaning unlimited, overage limits
+ * always enabled (they never block, they bill).
+ */
+function evaluateFeature(feature, count = 0) {
+    if (!feature)
+        return false;
+    if (feature.type === "limit") {
+        const limit = Number(feature.value);
+        return limit === -1 || count < limit;
+    }
+    if (feature.type === "limit_with_overage")
+        return true;
+    return Boolean(feature.value);
+}
 export class MantleKitClient {
     baseUrl;
     apiKey;
@@ -72,28 +91,43 @@ export class MantleKitClient {
     getPlans() {
         return this.request("GET", "/sdk/v1/plans", this.customerHeaders());
     }
-    /** The shop's own record: { plan, subscription, features }. Requires customerApiToken. */
+    /** The shop's own record — Mantle Customer shape: { plans, subscription: { plan, ... }, features, billingStatus }. */
     getCustomer() {
         return this.request("GET", "/sdk/v1/customer", this.customerHeaders());
     }
-    /** Convenience wrapper over getCustomer().features — mirrors MantleClient.isFeatureEnabled(). */
-    async isFeatureEnabled(featureKey) {
+    /**
+     * Mirrors MantleClient.isFeatureEnabled({ featureKey, count }) — limits
+     * evaluate as `count < limit` (-1 = unlimited). A bare string argument is
+     * also accepted: isFeatureEnabled("unlimited_bars").
+     */
+    async isFeatureEnabled(params) {
+        const { featureKey, count = 0 } = typeof params === "string" ? { featureKey: params, count: 0 } : params;
         const customer = await this.getCustomer();
-        return Boolean(customer.features[featureKey]?.value);
+        return evaluateFeature(customer.features[featureKey], count);
     }
-    /** Convenience wrapper over getCustomer().features — mirrors MantleClient.limitForFeature(). */
-    async limitForFeature(featureKey) {
+    /**
+     * Mirrors MantleClient.limitForFeature({ featureKey }) — resolves to -1
+     * when the feature is missing or not a limit type, exactly like Mantle.
+     */
+    async limitForFeature(params) {
+        const featureKey = typeof params === "string" ? params : params.featureKey;
         const customer = await this.getCustomer();
-        const value = customer.features[featureKey]?.value;
-        return typeof value === "number" ? value : null;
+        const feature = customer.features[featureKey];
+        if (!feature || (feature.type !== "limit" && feature.type !== "limit_with_overage"))
+            return -1;
+        return Number(feature.value);
     }
-    /** Start checkout for a plan. Returns a confirmationUrl to redirect the merchant's browser to. Requires customerApiToken. */
+    /**
+     * Start checkout for a plan. Resolves to the pending Subscription —
+     * redirect the merchant's browser to `subscription.confirmationUrl`.
+     * Requires customerApiToken.
+     */
     subscribe(params) {
         return this.request("POST", "/sdk/v1/subscribe", this.customerHeaders(), params);
     }
-    /** Cancel the shop's active subscription. Requires customerApiToken. */
-    cancelSubscription() {
-        return this.request("POST", "/sdk/v1/cancel-subscription", this.customerHeaders());
+    /** Cancel the shop's active subscription. Resolves to the cancelled Subscription. Requires customerApiToken. */
+    cancelSubscription(params) {
+        return this.request("POST", "/sdk/v1/cancel-subscription", this.customerHeaders(), params ?? {});
     }
     customerHeaders() {
         if (!this.customerApiToken)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sense-apps/mantle",
-  "version": "0.1.0",
-  "description": "Backend-only client for a self-hosted Mantlekit deployment — MantleClient-compatible API (identify, getPlans, getCustomer, subscribe) for Shopify apps.",
+  "version": "0.3.0",
+  "description": "Backend-only client for a self-hosted Mantlekit deployment — @heymantle/client-compatible shapes (Customer/Subscription/Plan/Feature) and API (identify, getPlans, getCustomer, subscribe) for Shopify apps.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.ts

@@ -1,13 +1,16 @@
 /**
- * @mantlekit/sdk — BACKEND-ONLY client library a merchant's OWN Shopify app
- * uses to talk to a Mantlekit deployment, the same way `@heymantle/client`
+ * @sense-apps/mantle — BACKEND-ONLY client library a merchant's OWN Shopify
+ * app uses to talk to a Mantlekit deployment, the same way `@heymantle/client`
  * (MantleClient) talks to api.heymantle.com — except `baseUrl` points at
  * YOUR domain, since you own the whole stack (no third party in the loop).
- * Constructor shape, method names (`identify`, `getCustomer`, `getPlans`,
- * `isFeatureEnabled`, `limitForFeature`), and the `customer.features`/
- * `customer.plan`/`customer.subscription` nesting deliberately mirror
- * MantleClient (see appapi.heymantle.dev/docs/understanding-mantleclient)
- * so porting off Mantle is close to a drop-in swap.
+ *
+ * Response shapes (Customer / Subscription / Plan / Feature) are aligned
+ * field-for-field with @heymantle/client@1.1.51 for everything Mantlekit
+ * supports, so Mantle-era code like
+ * `customer.subscription?.plan?.features["unlimited_bars"]?.value` ports
+ * unchanged. Mantle features Mantlekit doesn't have (Stripe billing,
+ * invoices, notifications, checklists, usage metrics reporting) are emitted
+ * as empty values on the payloads and have no client methods.
  *
  * This package has NO frontend/browser usage — every call (including the
  * customerApiToken-scoped ones) is meant to run on your own server. Your
@@ -34,39 +37,137 @@
  *   3. Store `apiToken` against that shop in your own DB.
  *   4. On any request from YOUR frontend (e.g. your pricing page's data loader):
  *      const client = new MantleKitClient({ customerApiToken: storedApiToken });
- *      const plans = await client.getPlans();
- *      const customer = await client.getCustomer(); // { plan, subscription, features }
+ *      const customer = await client.getCustomer();
+ *      const plan = customer.subscription?.plan ?? null; // full Mantle-shaped Plan
  *      // ...then your backend returns whatever subset of this your frontend needs.
  */
 
-export type FeatureType = "boolean" | "limit" | "limit_overage" | "string";
+/** Mantle spells Mantlekit's "limit_overage" as "limit_with_overage"; the API maps it on the way out. */
+export type FeatureType = "boolean" | "limit" | "limit_with_overage" | "string";
 
-export interface ResolvedFeature {
+export interface Feature {
+  id: string;
   key: string;
   name: string;
   type: FeatureType;
+  description: string | null;
   value: boolean | number | string;
+  displayOrder: number;
 }
 
-export interface ResolvedPlan {
-  planId: string;
+export interface UsageCharge {
+  id: string;
+  amount: number;
+  type: "unit";
+  terms: string;
+  cappedAmount: number;
+}
+
+export interface Discount {
+  id: string;
   name: string;
-  amount: string;
+  description: string | null;
+  /** Set for fixed-amount discounts. */
+  amount?: number;
+  amountCurrencyCode?: string;
+  presentmentAmount?: number;
+  presentmentCurrencyCode?: string;
+  /** Set for percentage discounts — human number, 20 = 20%. */
+  percentage?: number;
+  /** How many billing intervals the discount lasts; absent = forever. */
+  durationLimitInIntervals?: number;
+  /** The plan price after this discount. */
+  discountedAmount: number;
+  presentmentDiscountedAmount: number;
+}
+
+export interface Plan {
+  id: string;
+  name: string;
+  description: string | null;
+  availability: "public" | "customer" | "hidden";
+  type: "base";
   currencyCode: string;
+  presentmentAmount: number;
+  presentmentCurrencyCode: string;
+  /** Amount after discounts. Mantlekit has no discounts yet, so total === subtotal. */
+  total: number;
+  subtotal: number;
+  /** @deprecated Mantle deprecates this in favor of `subtotal`; kept for drop-in compat. */
+  amount: number;
+  public: boolean;
+  visible: boolean;
+  eligible: boolean;
   trialDays: number;
-  viaOverride: boolean;
-  features: Record<string, ResolvedFeature>;
+  interval: "EVERY_30_DAYS" | "ANNUAL" | "QUARTERLY";
+  features: Record<string, Feature>;
+  featuresOrder: string[];
+  usageCharges: UsageCharge[];
+  usageChargeCappedAmount?: number;
+  customFields: Record<string, unknown>;
+  /** Discounts attached to this plan (auto-apply and manual alike). */
+  discounts: Discount[];
+  /**
+   * The discount that auto-applies to this shop at subscribe time (targeted
+   * by plan/tags in the Mantlekit dashboard). `total` already reflects it;
+   * `subtotal` is the undiscounted price — render a slashed price when set.
+   */
+  autoAppliedDiscount?: Discount;
+  flexBilling: boolean;
+  flexBillingTerms: string | null;
+  autoUpgradeToPlanId: string | null;
+  createdAt?: string;
 }
 
-export interface ShopCustomer {
+export interface Subscription {
+  id: string;
+  plan: Plan;
+  lineItems: never[];
+  active: boolean;
+  activatedAt: string | null;
+  billingCycleAnchor: string | null;
+  currentPeriodStart: string | null;
+  currentPeriodEnd: string | null;
+  trialStartsAt: string | null;
+  trialExpiresAt: string | null;
+  cancelledAt: string | null;
+  createdAt: string | null;
+  features: Record<string, Feature>;
+  featuresOrder: string[];
+  usageCharges: UsageCharge[];
+  usageChargeCappedAmount?: number;
+  total: number;
+  subtotal: number;
+  presentmentTotal: number;
+  presentmentSubtotal: number;
+  /** Present on subscribe() responses — redirect the merchant's browser here. */
+  confirmationUrl?: string;
+  returnUrl?: string;
+  /** Mantlekit extra (not in Mantle's shape): raw status, e.g. "pending" | "active" | "cancelled". */
+  status: string;
+}
+
+export interface Customer {
   id: string;
-  myshopifyDomain: string;
   name: string | null;
   email: string | null;
+  test: boolean;
+  platform: "shopify";
+  platformId?: string;
+  myshopifyDomain: string;
   installedAt: string | null;
-  plan: { id: string; name: string } | null;
-  subscription: { status: string; trialEndsAt: string | null; currentPeriodEnd: string | null };
-  features: Record<string, ResolvedFeature>;
+  trialStartsAt: string | null;
+  trialExpiresAt: string | null;
+  /** The plans this shop is eligible for — same list as getPlans(). */
+  plans: Plan[];
+  subscription: Subscription | null;
+  paymentMethod: null;
+  features: Record<string, Feature>;
+  usage: Record<string, never>;
+  customFields: Record<string, unknown>;
+  usageCredits: never[];
+  reviews: never[];
+  billingStatus: "none" | "active" | "trialing" | "canceled" | "frozen";
 }
 
 export interface IdentifyParams {
@@ -92,16 +193,6 @@ export interface SubscribeParams {
   test?: boolean;
 }
 
-export interface SubscribeResult {
-  subscriptionId: string;
-  confirmationUrl: string;
-}
-
-export interface CancelSubscriptionResult {
-  id: string;
-  status: string;
-}
-
 export class MantleKitError extends Error {
   status: number;
   userErrors?: Array<{ field: string[] | null; message: string }>;
@@ -135,6 +226,21 @@ export interface MantleKitClientOptions {
 const env = (key: string): string | undefined =>
   typeof process !== "undefined" ? process.env?.[key] : undefined;
 
+/**
+ * Mirrors MantleClient's private evaluateFeature(): booleans by value,
+ * limits by `count < value` with -1 meaning unlimited, overage limits
+ * always enabled (they never block, they bill).
+ */
+function evaluateFeature(feature: Feature | undefined, count = 0): boolean {
+  if (!feature) return false;
+  if (feature.type === "limit") {
+    const limit = Number(feature.value);
+    return limit === -1 || count < limit;
+  }
+  if (feature.type === "limit_with_overage") return true;
+  return Boolean(feature.value);
+}
+
 export class MantleKitClient {
   private baseUrl: string;
   private apiKey?: string;
@@ -159,36 +265,50 @@ export class MantleKitClient {
   }
 
   /** Plans this shop is eligible for — what your pricing page renders. Requires customerApiToken. */
-  getPlans(): Promise<ResolvedPlan[]> {
-    return this.request<ResolvedPlan[]>("GET", "/sdk/v1/plans", this.customerHeaders());
+  getPlans(): Promise<Plan[]> {
+    return this.request<Plan[]>("GET", "/sdk/v1/plans", this.customerHeaders());
   }
 
-  /** The shop's own record: { plan, subscription, features }. Requires customerApiToken. */
-  getCustomer(): Promise<ShopCustomer> {
-    return this.request<ShopCustomer>("GET", "/sdk/v1/customer", this.customerHeaders());
+  /** The shop's own record — Mantle Customer shape: { plans, subscription: { plan, ... }, features, billingStatus }. */
+  getCustomer(): Promise<Customer> {
+    return this.request<Customer>("GET", "/sdk/v1/customer", this.customerHeaders());
   }
 
-  /** Convenience wrapper over getCustomer().features — mirrors MantleClient.isFeatureEnabled(). */
-  async isFeatureEnabled(featureKey: string): Promise<boolean> {
+  /**
+   * Mirrors MantleClient.isFeatureEnabled({ featureKey, count }) — limits
+   * evaluate as `count < limit` (-1 = unlimited). A bare string argument is
+   * also accepted: isFeatureEnabled("unlimited_bars").
+   */
+  async isFeatureEnabled(params: string | { featureKey: string; count?: number }): Promise<boolean> {
+    const { featureKey, count = 0 } = typeof params === "string" ? { featureKey: params, count: 0 } : params;
     const customer = await this.getCustomer();
-    return Boolean(customer.features[featureKey]?.value);
+    return evaluateFeature(customer.features[featureKey], count);
   }
 
-  /** Convenience wrapper over getCustomer().features — mirrors MantleClient.limitForFeature(). */
-  async limitForFeature(featureKey: string): Promise<number | null> {
+  /**
+   * Mirrors MantleClient.limitForFeature({ featureKey }) — resolves to -1
+   * when the feature is missing or not a limit type, exactly like Mantle.
+   */
+  async limitForFeature(params: string | { featureKey: string }): Promise<number> {
+    const featureKey = typeof params === "string" ? params : params.featureKey;
     const customer = await this.getCustomer();
-    const value = customer.features[featureKey]?.value;
-    return typeof value === "number" ? value : null;
+    const feature = customer.features[featureKey];
+    if (!feature || (feature.type !== "limit" && feature.type !== "limit_with_overage")) return -1;
+    return Number(feature.value);
   }
 
-  /** Start checkout for a plan. Returns a confirmationUrl to redirect the merchant's browser to. Requires customerApiToken. */
-  subscribe(params: SubscribeParams): Promise<SubscribeResult> {
-    return this.request<SubscribeResult>("POST", "/sdk/v1/subscribe", this.customerHeaders(), params);
+  /**
+   * Start checkout for a plan. Resolves to the pending Subscription —
+   * redirect the merchant's browser to `subscription.confirmationUrl`.
+   * Requires customerApiToken.
+   */
+  subscribe(params: SubscribeParams): Promise<Subscription> {
+    return this.request<Subscription>("POST", "/sdk/v1/subscribe", this.customerHeaders(), params);
   }
 
-  /** Cancel the shop's active subscription. Requires customerApiToken. */
-  cancelSubscription(): Promise<CancelSubscriptionResult> {
-    return this.request<CancelSubscriptionResult>("POST", "/sdk/v1/cancel-subscription", this.customerHeaders());
+  /** Cancel the shop's active subscription. Resolves to the cancelled Subscription. Requires customerApiToken. */
+  cancelSubscription(params?: { cancelReason?: string }): Promise<Subscription> {
+    return this.request<Subscription>("POST", "/sdk/v1/cancel-subscription", this.customerHeaders(), params ?? {});
   }
 
   private customerHeaders(): Record<string, string> {