@sense-apps/mantle 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @mantlekit/sdk
+
+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.
+
+**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
+```
+
+## Configure
+
+Set two env vars in your app (both server-side):
+
+```bash
+MANTLEKIT_URL=https://your-mantlekit-api.example.com
+MANTLEKIT_API_KEY=mk_...   # per-app API key, created in the Mantlekit dashboard under App → API
+```
+
+Then construct with no arguments:
+
+```ts
+import { MantleKitClient } from "@mantlekit/sdk";
+
+const admin = new MantleKitClient(); // reads MANTLEKIT_URL + MANTLEKIT_API_KEY
+```
+
+Explicit options always override env — useful for apps configured via a `config.json`, or when one process talks to more than one deployment:
+
+```ts
+const admin = new MantleKitClient({ baseUrl, apiKey });
+```
+
+## Auth model — two tiers, both server-side
+
+| Credential         | Where it lives                       | What it unlocks                                        |
+| ------------------ | ------------------------------------ | ------------------------------------------------------ |
+| `apiKey`           | your server's env                    | `identify()` only                                      |
+| `customerApiToken` | your DB, one per shop (returned by `identify()`) | everything else — `getPlans`, `getCustomer`, `subscribe`, `cancelSubscription` |
+
+`customerApiToken` has **no env fallback on purpose**: it is per-shop state, not deployment config. Store it next to the shop row in your own database.
+
+## Usage
+
+### 1. Register the shop after your OAuth callback
+
+```ts
+const admin = new MantleKitClient();
+const { shopId, apiToken } = await admin.identify({
+  myshopifyDomain: "cool-store.myshopify.com",
+  accessToken, // the offline token your OAuth flow just obtained
+  name: shop.name,
+  email: shop.email,
+});
+// persist apiToken on your shop record
+```
+
+`identify()` is an upsert — safe to call again on every app load to keep the shop record fresh.
+
+### 2. Per-shop client for everything else
+
+```ts
+const client = new MantleKitClient({ customerApiToken: shop.mantlekitToken });
+```
+
+### 3. Pricing page
+
+```ts
+const plans = await client.getPlans();
+// ResolvedPlan[]: planId, name, amount (string — money is never a float),
+// currencyCode, trialDays, viaOverride, features
+```
+
+Eligibility (tag rules, per-shop overrides) is resolved server-side by Mantlekit — the list you get back is exactly what this shop may buy.
+
+### 4. Subscribe / upgrade
+
+```ts
+const { confirmationUrl } = await client.subscribe({
+  planId,
+  returnUrl: `https://your-app.com/billing/confirm?shop=${shop.domain}`,
+});
+// redirect the merchant's browser to confirmationUrl (Shopify approval screen)
+```
+
+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()`.
+
+### 5. Gate features
+
+```ts
+const customer = await client.getCustomer();
+// { id, myshopifyDomain, plan, subscription: { status, trialEndsAt, ... }, features }
+
+if (await client.isFeatureEnabled("advanced_reports")) { ... }
+const maxSeats = await client.limitForFeature("team_seats"); // number | null
+```
+
+`isFeatureEnabled` / `limitForFeature` each call `getCustomer()` under the hood — if you need several flags in one request, call `getCustomer()` once and read `customer.features` yourself.
+
+### 6. Cancel
+
+```ts
+await client.cancelSubscription();
+```
+
+## Errors
+
+Every non-2xx response throws `MantleKitError` with `status` and, for validation failures, `userErrors: { field, message }[]`:
+
+```ts
+import { MantleKitError } from "@mantlekit/sdk";
+
+try {
+  await client.subscribe({ planId, returnUrl });
+} catch (e) {
+  if (e instanceof MantleKitError && e.status === 422) {
+    console.error(e.userErrors);
+  }
+}
+```

package/dist/client.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @mantlekit/sdk — 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.
+ *
+ * This package has NO frontend/browser usage — every call (including the
+ * customerApiToken-scoped ones) is meant to run on your own server. Your
+ * frontend never talks to Mantlekit directly; it talks to YOUR backend,
+ * which talks to Mantlekit and relays whatever shape your frontend needs.
+ *
+ * Two-tier auth, both server-side only:
+ *   - `apiKey` — scopes `identify()`. Belongs in your server's env, never in
+ *     client-shipped code.
+ *   - `customerApiToken` — the per-shop credential `identify()` returns.
+ *     Scopes everything else (getPlans, getCustomer, subscribe,
+ *     cancelSubscription) to that one shop. Store it in YOUR OWN database
+ *     next to that shop's row; still server-side only.
+ *
+ * Configuration comes from env by default — set MANTLEKIT_URL and
+ * MANTLEKIT_API_KEY in your app's env and construct with no arguments.
+ * Explicit options always win over env (for apps configured via config.json
+ * or when talking to more than one deployment).
+ *
+ * Typical flow, entirely within your app's backend:
+ *   1. Your app's OWN OAuth callback finishes and you have a shop + access token.
+ *   2. const admin = new MantleKitClient(); // MANTLEKIT_URL + MANTLEKIT_API_KEY from env
+ *      const { apiToken } = await admin.identify({ myshopifyDomain, accessToken });
+ *   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 }
+ *      // ...then your backend returns whatever subset of this your frontend needs.
+ */
+export type FeatureType = "boolean" | "limit" | "limit_overage" | "string";
+export interface ResolvedFeature {
+    key: string;
+    name: string;
+    type: FeatureType;
+    value: boolean | number | string;
+}
+export interface ResolvedPlan {
+    planId: string;
+    name: string;
+    amount: string;
+    currencyCode: string;
+    trialDays: number;
+    viaOverride: boolean;
+    features: Record<string, ResolvedFeature>;
+}
+export interface ShopCustomer {
+    id: string;
+    myshopifyDomain: string;
+    name: string | null;
+    email: string | null;
+    installedAt: string | null;
+    plan: {
+        id: string;
+        name: string;
+    } | null;
+    subscription: {
+        status: string;
+        trialEndsAt: string | null;
+        currentPeriodEnd: string | null;
+    };
+    features: Record<string, ResolvedFeature>;
+}
+export interface IdentifyParams {
+    myshopifyDomain: string;
+    /** Pass this along if your app already obtained one via its own Shopify OAuth. */
+    accessToken?: string;
+    name?: string;
+    email?: string;
+    /** Matches MantleClient.identify()'s shape; defaults to "shopify". */
+    platform?: string;
+    platformId?: string;
+}
+export interface IdentifyResult {
+    shopId: string;
+    apiToken: string;
+}
+export interface SubscribeParams {
+    planId: string;
+    /** Where to send the merchant after Shopify's approval screen — your app's own URL. */
+    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<{
+        field: string[] | null;
+        message: string;
+    }>;
+    constructor(status: number, message: string, userErrors?: Array<{
+        field: string[] | null;
+        message: string;
+    }>);
+}
+export interface MantleKitClientOptions {
+    /**
+     * Your own Mantlekit API deployment, e.g. "https://billing.yourcompany.com".
+     * Falls back to the MANTLEKIT_URL env var.
+     */
+    baseUrl?: string;
+    /**
+     * Server-side only — scopes identify(). Never expose this to a browser.
+     * Falls back to the MANTLEKIT_API_KEY env var.
+     */
+    apiKey?: string;
+    /**
+     * Client-safe, per-shop token from identify() — scopes every other method.
+     * No env fallback on purpose: it is per-shop state that lives in your DB,
+     * not deployment config.
+     */
+    customerApiToken?: string;
+}
+export declare class MantleKitClient {
+    private baseUrl;
+    private apiKey?;
+    private customerApiToken?;
+    constructor(options?: MantleKitClientOptions);
+    /** 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>;
+    private customerHeaders;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,115 @@
+/**
+ * @mantlekit/sdk — 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.
+ *
+ * This package has NO frontend/browser usage — every call (including the
+ * customerApiToken-scoped ones) is meant to run on your own server. Your
+ * frontend never talks to Mantlekit directly; it talks to YOUR backend,
+ * which talks to Mantlekit and relays whatever shape your frontend needs.
+ *
+ * Two-tier auth, both server-side only:
+ *   - `apiKey` — scopes `identify()`. Belongs in your server's env, never in
+ *     client-shipped code.
+ *   - `customerApiToken` — the per-shop credential `identify()` returns.
+ *     Scopes everything else (getPlans, getCustomer, subscribe,
+ *     cancelSubscription) to that one shop. Store it in YOUR OWN database
+ *     next to that shop's row; still server-side only.
+ *
+ * Configuration comes from env by default — set MANTLEKIT_URL and
+ * MANTLEKIT_API_KEY in your app's env and construct with no arguments.
+ * Explicit options always win over env (for apps configured via config.json
+ * or when talking to more than one deployment).
+ *
+ * Typical flow, entirely within your app's backend:
+ *   1. Your app's OWN OAuth callback finishes and you have a shop + access token.
+ *   2. const admin = new MantleKitClient(); // MANTLEKIT_URL + MANTLEKIT_API_KEY from env
+ *      const { apiToken } = await admin.identify({ myshopifyDomain, accessToken });
+ *   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 }
+ *      // ...then your backend returns whatever subset of this your frontend needs.
+ */
+export class MantleKitError extends Error {
+    status;
+    userErrors;
+    constructor(status, message, userErrors) {
+        super(message);
+        this.name = "MantleKitError";
+        this.status = status;
+        this.userErrors = userErrors;
+    }
+}
+const env = (key) => typeof process !== "undefined" ? process.env?.[key] : undefined;
+export class MantleKitClient {
+    baseUrl;
+    apiKey;
+    customerApiToken;
+    constructor(options = {}) {
+        const baseUrl = options.baseUrl ?? env("MANTLEKIT_URL");
+        if (!baseUrl) {
+            throw new Error("MantleKitClient requires a baseUrl — pass { baseUrl } or set the MANTLEKIT_URL env var to your Mantlekit API deployment");
+        }
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.apiKey = options.apiKey ?? env("MANTLEKIT_API_KEY");
+        this.customerApiToken = options.customerApiToken;
+    }
+    /** Register (or re-sync) a shop after your app's own Shopify OAuth completes. Requires apiKey. */
+    identify(params) {
+        if (!this.apiKey)
+            throw new Error("identify() requires apiKey — call this from your server, never a browser");
+        return this.request("POST", "/sdk/v1/identify", { "X-Api-Key": this.apiKey }, { platform: "shopify", ...params });
+    }
+    /** Plans this shop is eligible for — what your pricing page renders. Requires customerApiToken. */
+    getPlans() {
+        return this.request("GET", "/sdk/v1/plans", this.customerHeaders());
+    }
+    /** The shop's own record: { plan, subscription, features }. Requires customerApiToken. */
+    getCustomer() {
+        return this.request("GET", "/sdk/v1/customer", this.customerHeaders());
+    }
+    /** Convenience wrapper over getCustomer().features — mirrors MantleClient.isFeatureEnabled(). */
+    async isFeatureEnabled(featureKey) {
+        const customer = await this.getCustomer();
+        return Boolean(customer.features[featureKey]?.value);
+    }
+    /** Convenience wrapper over getCustomer().features — mirrors MantleClient.limitForFeature(). */
+    async limitForFeature(featureKey) {
+        const customer = await this.getCustomer();
+        const value = customer.features[featureKey]?.value;
+        return typeof value === "number" ? value : null;
+    }
+    /** Start checkout for a plan. Returns a confirmationUrl to redirect the merchant's browser to. 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());
+    }
+    customerHeaders() {
+        if (!this.customerApiToken)
+            throw new Error("This call requires customerApiToken — obtain one via identify() first");
+        return { "X-Customer-Api-Token": this.customerApiToken };
+    }
+    async request(method, path, headers, body) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: { "Content-Type": "application/json", ...headers },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok) {
+            throw new MantleKitError(res.status, json?.error ?? `Request failed: ${res.status}`, json?.userErrors);
+        }
+        return json;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./client";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./client";

package/package.json

@@ -0,0 +1,30 @@
+{
+  "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.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "sideEffects": false,
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run typecheck && bun run build"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5"
+  }
+}

package/src/client.ts

@@ -0,0 +1,213 @@
+/**
+ * @mantlekit/sdk — 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.
+ *
+ * This package has NO frontend/browser usage — every call (including the
+ * customerApiToken-scoped ones) is meant to run on your own server. Your
+ * frontend never talks to Mantlekit directly; it talks to YOUR backend,
+ * which talks to Mantlekit and relays whatever shape your frontend needs.
+ *
+ * Two-tier auth, both server-side only:
+ *   - `apiKey` — scopes `identify()`. Belongs in your server's env, never in
+ *     client-shipped code.
+ *   - `customerApiToken` — the per-shop credential `identify()` returns.
+ *     Scopes everything else (getPlans, getCustomer, subscribe,
+ *     cancelSubscription) to that one shop. Store it in YOUR OWN database
+ *     next to that shop's row; still server-side only.
+ *
+ * Configuration comes from env by default — set MANTLEKIT_URL and
+ * MANTLEKIT_API_KEY in your app's env and construct with no arguments.
+ * Explicit options always win over env (for apps configured via config.json
+ * or when talking to more than one deployment).
+ *
+ * Typical flow, entirely within your app's backend:
+ *   1. Your app's OWN OAuth callback finishes and you have a shop + access token.
+ *   2. const admin = new MantleKitClient(); // MANTLEKIT_URL + MANTLEKIT_API_KEY from env
+ *      const { apiToken } = await admin.identify({ myshopifyDomain, accessToken });
+ *   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 }
+ *      // ...then your backend returns whatever subset of this your frontend needs.
+ */
+
+export type FeatureType = "boolean" | "limit" | "limit_overage" | "string";
+
+export interface ResolvedFeature {
+  key: string;
+  name: string;
+  type: FeatureType;
+  value: boolean | number | string;
+}
+
+export interface ResolvedPlan {
+  planId: string;
+  name: string;
+  amount: string;
+  currencyCode: string;
+  trialDays: number;
+  viaOverride: boolean;
+  features: Record<string, ResolvedFeature>;
+}
+
+export interface ShopCustomer {
+  id: string;
+  myshopifyDomain: string;
+  name: string | null;
+  email: string | null;
+  installedAt: string | null;
+  plan: { id: string; name: string } | null;
+  subscription: { status: string; trialEndsAt: string | null; currentPeriodEnd: string | null };
+  features: Record<string, ResolvedFeature>;
+}
+
+export interface IdentifyParams {
+  myshopifyDomain: string;
+  /** Pass this along if your app already obtained one via its own Shopify OAuth. */
+  accessToken?: string;
+  name?: string;
+  email?: string;
+  /** Matches MantleClient.identify()'s shape; defaults to "shopify". */
+  platform?: string;
+  platformId?: string;
+}
+
+export interface IdentifyResult {
+  shopId: string;
+  apiToken: string;
+}
+
+export interface SubscribeParams {
+  planId: string;
+  /** Where to send the merchant after Shopify's approval screen — your app's own URL. */
+  returnUrl: string;
+  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 }>;
+  constructor(status: number, message: string, userErrors?: Array<{ field: string[] | null; message: string }>) {
+    super(message);
+    this.name = "MantleKitError";
+    this.status = status;
+    this.userErrors = userErrors;
+  }
+}
+
+export interface MantleKitClientOptions {
+  /**
+   * Your own Mantlekit API deployment, e.g. "https://billing.yourcompany.com".
+   * Falls back to the MANTLEKIT_URL env var.
+   */
+  baseUrl?: string;
+  /**
+   * Server-side only — scopes identify(). Never expose this to a browser.
+   * Falls back to the MANTLEKIT_API_KEY env var.
+   */
+  apiKey?: string;
+  /**
+   * Client-safe, per-shop token from identify() — scopes every other method.
+   * No env fallback on purpose: it is per-shop state that lives in your DB,
+   * not deployment config.
+   */
+  customerApiToken?: string;
+}
+
+const env = (key: string): string | undefined =>
+  typeof process !== "undefined" ? process.env?.[key] : undefined;
+
+export class MantleKitClient {
+  private baseUrl: string;
+  private apiKey?: string;
+  private customerApiToken?: string;
+
+  constructor(options: MantleKitClientOptions = {}) {
+    const baseUrl = options.baseUrl ?? env("MANTLEKIT_URL");
+    if (!baseUrl) {
+      throw new Error(
+        "MantleKitClient requires a baseUrl — pass { baseUrl } or set the MANTLEKIT_URL env var to your Mantlekit API deployment"
+      );
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey ?? env("MANTLEKIT_API_KEY");
+    this.customerApiToken = options.customerApiToken;
+  }
+
+  /** Register (or re-sync) a shop after your app's own Shopify OAuth completes. Requires apiKey. */
+  identify(params: IdentifyParams): Promise<IdentifyResult> {
+    if (!this.apiKey) throw new Error("identify() requires apiKey — call this from your server, never a browser");
+    return this.request<IdentifyResult>("POST", "/sdk/v1/identify", { "X-Api-Key": this.apiKey }, { platform: "shopify", ...params });
+  }
+
+  /** 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());
+  }
+
+  /** The shop's own record: { plan, subscription, features }. Requires customerApiToken. */
+  getCustomer(): Promise<ShopCustomer> {
+    return this.request<ShopCustomer>("GET", "/sdk/v1/customer", this.customerHeaders());
+  }
+
+  /** Convenience wrapper over getCustomer().features — mirrors MantleClient.isFeatureEnabled(). */
+  async isFeatureEnabled(featureKey: string): Promise<boolean> {
+    const customer = await this.getCustomer();
+    return Boolean(customer.features[featureKey]?.value);
+  }
+
+  /** Convenience wrapper over getCustomer().features — mirrors MantleClient.limitForFeature(). */
+  async limitForFeature(featureKey: string): Promise<number | null> {
+    const customer = await this.getCustomer();
+    const value = customer.features[featureKey]?.value;
+    return typeof value === "number" ? value : null;
+  }
+
+  /** 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);
+  }
+
+  /** Cancel the shop's active subscription. Requires customerApiToken. */
+  cancelSubscription(): Promise<CancelSubscriptionResult> {
+    return this.request<CancelSubscriptionResult>("POST", "/sdk/v1/cancel-subscription", this.customerHeaders());
+  }
+
+  private customerHeaders(): Record<string, string> {
+    if (!this.customerApiToken) throw new Error("This call requires customerApiToken — obtain one via identify() first");
+    return { "X-Customer-Api-Token": this.customerApiToken };
+  }
+
+  private async request<T>(method: string, path: string, headers: Record<string, string>, body?: unknown): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: { "Content-Type": "application/json", ...headers },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const json = (await res.json().catch(() => null)) as
+      | { error?: string; userErrors?: Array<{ field: string[] | null; message: string }> }
+      | null;
+    if (!res.ok) {
+      throw new MantleKitError(res.status, json?.error ?? `Request failed: ${res.status}`, json?.userErrors);
+    }
+    return json as T;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./client";