@classytic/commerce-client 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.1.1 — 2026-10-20
+
+Add tenant-scoped media removal through the guarded media resource, and type media folder, size and display metadata for Fluid library bindings. Report unsupported source formats and browser decoding failures before starting storage writes.
+
+Add `@classytic/commerce-client/platform`: `createPlatformClient({ apiUrl, token })` for platform administration with a bearer token and no merchant organization. `organizations.list` pages organizations and `organizations.decide(id, { action, expectedStatus, note })` applies an approve, reject, suspend or reactivate decision (matches `@spinekit/auth` 0.17.0 `./organizations`).
+
+Dependencies are already at the latest published (`arc-next` 0.18.0, `media-transform` 0.3.0, `primitives` 0.34.0).
+
+## 0.1.0 — 2026-10-20
+
+First publish.
+
+Expose storefront tag/collection/sale/price/sort queries and public taxonomy/compare-at prices; type merchant taxonomy and compare-at writes.
+
+Add typed category trees, hierarchy choices, parent/description/image fields and category image uploads. Category updates exclude immutable slugs.
+
+API-key lifetime options expose optional non-expiry support; creation accepts explicit `expiresInDays: null`.
+
+Delivery quote inputs include destination country; the storefront sends it when requesting prices.
+
+Add a bounded store sales overview and tenant-scoped delivery settings. Public storefront clients can load delivery districts/areas and request server-priced delivery quotes without merchant credentials.
+
+Typed store profiles, catalog reads, guest checkout with explicit retry keys, and private order tracking.
+
+The isolated `/management` entry supports merchant catalog/media, order commands
+and cash collection, store settings, Telegram connections and delivery history,
+plus API-key options, creation, rotation and revocation.
+
+Platform administration: `./platform` exposes bearer-only organization lists and guarded status decisions without requiring a merchant organization.

package/LICENSE

@@ -0,0 +1,75 @@
+Classytic Source-Available License (Community & Commercial), Version 1.0
+
+Copyright (c) 2026 Classytic LLC. All rights reserved.
+
+This software is source-available, not open source. Please read this License
+before using it.
+
+1. DEFINITIONS
+   "Software" means the contents of this package and any accompanying source
+   code, object code, or documentation, in any form.
+   "Licensor" means Classytic LLC, a limited liability company organized in the
+   United States.
+   "You" means the individual or legal entity exercising rights under this
+   License.
+   "Evaluation Use" means use for evaluation, development, testing,
+   experimentation, or internal non-commercial purposes only.
+   "Production Use" means any use of the Software that is live, commercial,
+   revenue-generating, or customer-facing, or any use other than Evaluation Use.
+   "Commercial License" means a separate written agreement executed with
+   Licensor that grants Production Use rights.
+
+2. OWNERSHIP
+   The Software is licensed, not sold. Licensor retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+   All rights not expressly granted in this License are reserved by Licensor.
+
+3. EVALUATION GRANT
+   Subject to Your compliance with this License, Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable, revocable license
+   to download, install, run, and modify the Software solely for Evaluation Use.
+
+4. PRODUCTION USE REQUIRES A COMMERCIAL LICENSE
+   Production Use of the Software is NOT permitted under this License and
+   requires a Commercial License from Licensor. A Commercial License may be
+   granted at Licensor's discretion, with or without a fee, and may confer
+   perpetual, irrevocable, and transferable Production Use rights as set out in
+   that agreement. Contact licensing@classytic.com to obtain one.
+
+5. RESTRICTIONS
+   You may not:
+   (a) make any Production Use of the Software without a Commercial License;
+   (b) redistribute, resell, rent, sublicense, or otherwise make the Software
+       (in whole or in part, original or modified) available to third parties as
+       a stand-alone product, framework, library, or hosted/managed service that
+       competes with the Software or with Licensor;
+   (c) remove, obscure, or alter any copyright, license, or attribution notice.
+
+6. FEEDBACK AND CONTRIBUTIONS
+   Any feedback, suggestions, or contributions You provide relating to the
+   Software may be used by Licensor for any purpose without obligation to You.
+
+7. TERMINATION
+   This License and the Evaluation Grant terminate automatically if You breach
+   any term. Upon termination You must cease all use of the Software and destroy
+   all copies in Your possession. Rights under a Commercial License are governed
+   by that agreement's own terms and survive termination of this License to the
+   extent stated there.
+
+8. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR BE LIABLE
+   FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+   TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+10. GOVERNING LAW
+   This License is governed by the laws of the State of Delaware, United States,
+   without regard to its conflict-of-laws principles. (Adjust to Your LLC's state
+   of formation.)
+
+For commercial licensing, contact: licensing@classytic.com

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @classytic/commerce-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@classytic/commerce-client` calls the shared Spine storefront resources.
+It exposes profile, catalog, guest checkout and order tracking. The backend must
+compose those resources, as Classytic Commerce does; the ERP's older checkout endpoints have
+a different contract.
+
+Install with `npm install @classytic/commerce-client`.
+
+Use Arc Next 0.17 or later. This entry uses its server-safe client/API subpaths;
+it imports no React hooks, Next.js APIs, merchant credentials or server kernels.
+
+```ts
+import { createStorefrontClient } from '@classytic/commerce-client';
+import type { GuestCheckoutInput } from '@classytic/commerce-client/types';
+
+const shop = createStorefrontClient({
+  apiUrl: 'http://localhost:4140/api/v1', // Full API mount, including its prefix.
+  store: 'store-alpha',
+});
+const profile = await shop.profile();
+const page = await shop.products({ limit: 20, category: 'mugs' });
+const next = page.next ? await shop.products({ after: page.next, limit: 20, category: 'mugs' }) : null;
+const categories = await shop.categories();
+// category=clothing includes products assigned to its descendants.
+const product = await shop.product('blue-mug');
+```
+
+Each instance captures its API mount and store. Dashboard `configureClient` and
+`configureAuth` settings cannot change its routing or add credentials. Cookies
+are omitted. Construct separate instances for separate stores or SSR requests.
+
+## Checkout from a frontend cart
+
+```ts
+const input: GuestCheckoutInput = {
+  lines: [{ productId: product.id, quantity: 2 }],
+  customer: { name: 'Buyer', phone: '01712345678' },
+  shippingAddress: { line1: 'Road 4', city: 'Dhaka', country: 'BD' },
+};
+// Create once for this attempt, outside any retry handler.
+const idempotencyKey = crypto.randomUUID();
+const placed = await shop.checkout(input, { idempotencyKey });
+const status = await shop.orderStatus(placed);
+```
+
+Keep the input and key unchanged when retrying a lost response. Use a new key
+when the buyer intentionally starts another order. The SDK does not generate a
+fallback key. The server resolves prices, publication, variants, delivery charges
+and totals. Multiple active variants require `variantSku` on each relevant line.
+Do not send prices or lifecycle/payment state.
+
+Money stays in integer minor units. Display it using the primitives money helpers;
+do not assume every currency has two decimal places. This client does no pricing
+arithmetic and stores no cart.
+
+The checkout result includes an access token bound to that store and order. Keep
+it privately for the buyer; the SDK puts it in `x-order-access`, never the URL.
+It does not persist tokens or place them in logs. Status reads use `no-store` and
+omit buyer contact/address. Shipment and delivery are fulfillment facts; delivery
+alone does not establish COD collection.
+
+## Requests and errors
+
+Read methods accept an optional `{ signal }`; checkout takes it alongside its
+required `idempotencyKey`. The client timeout defaults to 15 seconds and can be
+configured with `timeoutMs`. A custom `fetch` transport is available for embedding
+and tests; ordinary browser/Node consumers use the runtime's fetch.
+
+```ts
+import { isArcApiError } from '@classytic/arc-next/client';
+
+try {
+  await shop.checkout(input, { idempotencyKey });
+} catch (error) {
+  if (isArcApiError(error)) {
+    // Inspect status/code/fieldErrors; preserve the attempt key for a retry.
+    console.error(error.code, error.fieldErrors);
+  }
+}
+```
+
+Arc Next owns HTTP parsing, timeouts and the canonical error contract. Category
+reads return the data array; product pages retain their cursor metadata.
+The server remains the authority for validation;
+unknown filters and extra checkout fields fail there.
+
+Products use bounded cursor pages. Categories currently return at most 100 active
+entries. Merchant catalog/order CRUD, integrations, key management and React hooks
+are outside this public client.
+
+`products({ q, category, limit, after })` searches product names literally,
+case-insensitively, inside the selected store’s published catalog. Search terms
+are limited to 100 characters. Pagination preserves the same search/category
+filters; `next: null` marks the final page.
+
+## Merchant dashboard and backend clients
+
+Use the separate [`/management` entry](management.md) for authenticated products,
+categories, media, order commands, store settings, Telegram connections,
+notification delivery history and API keys. The root entry remains isolated for
+public storefronts.
+
+Delivery quotes accept `country` alongside `lines` and `areaId`. Send the destination
+country when known so the preview applies the same country restriction as checkout.
+
+`/category-tree` exports framework-independent `categoryNavigation` and
+`categoryChoices` helpers. Public categories include `parent`, `parentPath`,
+`description`, `image` and `displayOrder`; navigation omits children whose parents
+are absent from the public category list.
+
+## Storefront product filters
+
+```ts
+const featured = await shop.products({ collection: 'featured', limit: 8 });
+const summerSale = await shop.products({ tag: 'summer', onSale: true, limit: 8 });
+const affordable = await shop.products({ category: 'clothing', minPrice: 0, maxPrice: 100000, sort: 'price-asc' });
+```
+
+Filters combine with AND. A tag or collection matches its exact stored name.
+`category` includes descendants; `q` searches product names literally. Price bounds
+are inclusive integer minor units on the product's base price; variant adjustments
+are not part of that range. Sort values are `newest` (default), `price-asc` and
+`price-desc`. Price sorting includes products with a numeric base price.
+
+`next` is an opaque Mongokit cursor: pass it back as `after` with the same filters
+and sort. Restart pagination when filters change. Public calls always enforce the
+resolved store and published/priced visibility, and reject unknown query fields.
+Merchant `products.getAll({ params })` continues to use Arc's normal allowed query
+syntax, including tags, collections and base-price bracket filters.

package/dist/category-tree.d.ts

@@ -0,0 +1,20 @@
+//#region src/category-tree.d.ts
+export interface CategoryBranch {
+  name: string;
+  slug: string;
+  children?: readonly CategoryBranch[];
+}
+export interface CategoryChoice {
+  value: string;
+  label: string;
+  depth: number;
+}
+/** Flatten a category tree into breadcrumb choices, excluding a complete subtree when editing its parent. */
+export declare function categoryChoices(nodes: readonly CategoryBranch[], excludeSlug?: string): CategoryChoice[];
+/** Group the public flat projection into a navigation tree; children of missing parents stay unlisted. */
+export declare function categoryNavigation(rows: readonly {
+  name: string;
+  slug: string;
+  parent?: string | null;
+}[]): CategoryBranch[];
+//#endregion

package/dist/category-tree.js

@@ -0,0 +1,39 @@
+//#region src/category-tree.ts
+/** Flatten a category tree into breadcrumb choices, excluding a complete subtree when editing its parent. */
+function categoryChoices(nodes, excludeSlug) {
+	function visit(items, path, seen) {
+		return items.flatMap((item) => {
+			if (item.slug === excludeSlug) return [];
+			if (seen.has(item.slug) || path.length > 20) throw new Error("Invalid category hierarchy.");
+			const branch = [...path, item.name];
+			return [{
+				value: item.slug,
+				label: branch.join(" / "),
+				depth: path.length
+			}, ...visit(item.children ?? [], branch, /* @__PURE__ */ new Set([...seen, item.slug]))];
+		});
+	}
+	return visit(nodes, [], /* @__PURE__ */ new Set());
+}
+/** Group the public flat projection into a navigation tree; children of missing parents stay unlisted. */
+function categoryNavigation(rows) {
+	const nodes = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		if (nodes.has(row.slug)) throw new Error("Duplicate category slug.");
+		nodes.set(row.slug, {
+			name: row.name,
+			slug: row.slug,
+			children: []
+		});
+	}
+	const roots = [];
+	for (const row of rows) {
+		const node = nodes.get(row.slug);
+		if (!node) throw new Error("Category navigation is incomplete.");
+		if (row.parent) nodes.get(row.parent)?.children.push(node);
+		else roots.push(node);
+	}
+	return roots;
+}
+//#endregion
+export { categoryChoices, categoryNavigation };

package/dist/delivery-types.d.ts

@@ -0,0 +1,48 @@
+//#region src/delivery-types.d.ts
+export interface DeliveryRules {
+  mode: 'flat' | 'zones';
+  zones: Array<{
+    name: string;
+    chargeMinor: number;
+    districts: string[];
+  }>;
+  freeOverMinor: number | null;
+}
+export interface DeliverySettings {
+  deliveryChargeMinor: number;
+  deliveryRules: DeliveryRules;
+  version: number | null;
+}
+export interface DeliverySettingsUpdate {
+  deliveryChargeMinor: number;
+  deliveryRules: DeliveryRules;
+  expectedVersion: number | null;
+}
+export interface DeliveryDistrict {
+  id: string;
+  name: string;
+  divisionId: string;
+  divisionName: string;
+}
+export interface DeliveryArea {
+  id: number;
+  name: string;
+  districtName: string;
+}
+export interface DeliveryQuoteInput {
+  lines: Array<{
+    productId: string;
+    variantSku?: string;
+    quantity: number;
+  }>;
+  areaId?: number;
+  country?: string;
+}
+export interface DeliveryQuote {
+  subtotalMinor: number;
+  deliveryChargeMinor: number;
+  currency: string;
+  zone?: string;
+  freeDelivery?: boolean;
+}
+//#endregion

package/dist/delivery-types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { DeliveryArea, DeliveryDistrict, DeliveryQuote, DeliveryQuoteInput } from "./delivery-types.js";
+import { a as StorefrontCategory, c as StorefrontProductPage, d as StorefrontRequestOptions, i as GuestOrderAccess, l as StorefrontProductQuery, n as GuestCheckoutOptions, o as StorefrontOrder, r as GuestCheckoutResult, s as StorefrontProduct, t as GuestCheckoutInput, u as StorefrontProfile } from "./types-C0cSi6Pk.js";
+import { ArcClientConfig } from "@classytic/arc-next/client";
+//#region src/index.d.ts
+export interface StorefrontClientOptions {
+  /** Full API mount, for example https://api.example.com/api/v1. */
+  apiUrl: string;
+  store: string;
+  timeoutMs?: number;
+  fetch?: ArcClientConfig['fetch'];
+}
+/** Build an isolated guest client; never inherit dashboard credentials or global routing. */
+export declare function createStorefrontClient(options: StorefrontClientOptions): {
+  profile: (request?: StorefrontRequestOptions) => Promise<StorefrontProfile>;
+  products: (query?: StorefrontProductQuery, request?: StorefrontRequestOptions) => Promise<StorefrontProductPage>;
+  product: (slug: string, request?: StorefrontRequestOptions) => Promise<StorefrontProduct>;
+  categories: (request?: StorefrontRequestOptions) => Promise<StorefrontCategory[]>;
+  deliveryDistricts: (request?: StorefrontRequestOptions) => Promise<{
+    requiresArea: boolean;
+    data: DeliveryDistrict[];
+  }>;
+  deliveryAreas: (district: string, request?: StorefrontRequestOptions) => Promise<{
+    data: DeliveryArea[];
+  }>;
+  quoteDelivery: (input: DeliveryQuoteInput, request?: StorefrontRequestOptions) => Promise<DeliveryQuote>;
+  checkout: (input: GuestCheckoutInput, request: GuestCheckoutOptions) => Promise<GuestCheckoutResult>;
+  orderStatus: (access: GuestOrderAccess, request?: StorefrontRequestOptions) => Promise<StorefrontOrder>;
+};
+export type StorefrontClient = ReturnType<typeof createStorefrontClient>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,66 @@
+import { BaseApi } from "@classytic/arc-next/api";
+import { createClient } from "@classytic/arc-next/client";
+//#region src/index.ts
+function segment(value) {
+	if (!value || value === "." || value === "..") throw new Error("A nonempty resource identifier is required.");
+	return encodeURIComponent(value);
+}
+/** Build an isolated guest client; never inherit dashboard credentials or global routing. */
+function createStorefrontClient(options) {
+	const store = options.store;
+	const url = new URL(options.apiUrl);
+	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error("apiUrl must be an HTTP(S) API mount without credentials, query or fragment.");
+	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(store)) throw new Error("A valid store slug is required.");
+	const config = {
+		client: createClient({
+			baseUrl: url.href.replace(/\/+$/, ""),
+			getToken: () => null,
+			getOrgId: () => null,
+			credentials: "omit",
+			autoIdempotency: false,
+			timeoutMs: options.timeoutMs ?? 15e3,
+			...options.fetch ? { fetch: options.fetch } : {}
+		}),
+		basePath: "",
+		cache: "no-store"
+	};
+	const catalog = new BaseApi(`storefront/${segment(store)}`, config);
+	const profiles = new BaseApi("stores", config);
+	return {
+		profile: (request = {}) => profiles.request("GET", `${profiles.baseUrl}/${segment(store)}`, { options: request }),
+		products: (query = {}, request = {}) => catalog.request("GET", `${catalog.baseUrl}/products`, {
+			params: { ...query },
+			options: request
+		}),
+		product: (slug, request = {}) => catalog.request("GET", `${catalog.baseUrl}/products/${segment(slug)}`, { options: request }),
+		categories: async (request = {}) => {
+			return (await catalog.request("GET", `${catalog.baseUrl}/categories`, { options: request })).data;
+		},
+		deliveryDistricts: (request = {}) => catalog.request("GET", `${catalog.baseUrl}/delivery/districts`, { options: request }),
+		deliveryAreas: (district, request = {}) => catalog.request("GET", `${catalog.baseUrl}/delivery/areas`, {
+			params: { district },
+			options: request
+		}),
+		quoteDelivery: (input, request = {}) => catalog.request("POST", `${catalog.baseUrl}/orders/quote`, {
+			data: input,
+			options: request
+		}),
+		checkout: (input, request) => {
+			if (!request?.idempotencyKey?.trim()) throw new Error("idempotencyKey is required; preserve it for retries.");
+			return catalog.request("POST", `${catalog.baseUrl}/orders`, {
+				data: input,
+				options: {
+					signal: request.signal,
+					headerOptions: { "Idempotency-Key": request.idempotencyKey }
+				}
+			});
+		},
+		orderStatus: (access, request = {}) => catalog.request("GET", `${catalog.baseUrl}/orders/${segment(access.orderNumber)}/status`, { options: {
+			signal: request.signal,
+			cache: "no-store",
+			headerOptions: { "x-order-access": access.accessToken }
+		} })
+	};
+}
+//#endregion
+export { createStorefrontClient };

package/dist/management-types.d.ts

@@ -0,0 +1,230 @@
+import { o as StorefrontOrder, s as StorefrontProduct } from "./types-C0cSi6Pk.js";
+import { Address } from "@classytic/primitives/address";
+import { Money } from "@classytic/primitives/money";
+//#region src/management-types.d.ts
+export interface ProductInput {
+  name: string;
+  slug: string;
+  productType: 'physical';
+  status: 'draft' | 'active' | 'archived';
+  description?: string;
+  categorySlug?: string;
+  tags?: string[];
+  collections?: string[];
+  images?: StorefrontProduct['images'];
+  defaultMonetization: {
+    type: 'one_time';
+    pricing: {
+      basePrice: Money;
+      currency: string;
+      compareAtPrice?: Money;
+    };
+  };
+  variationAttributes?: Array<{
+    code: string;
+    name: string;
+    values: Array<{
+      code: string;
+      label: string;
+    }>;
+  }>;
+  variants?: Array<{
+    sku: string;
+    attributes: Record<string, string>;
+    priceModifier: number;
+    isActive: boolean;
+  }>;
+}
+export interface MerchantProduct extends ProductInput {
+  _id: string;
+  updatedAt: string;
+}
+export interface CategoryInput {
+  name: string;
+  /** Omit on create to generate from the name. Slugs are immutable after creation. */
+  slug?: string;
+  parent?: string | null;
+  description?: string;
+  image?: {
+    url: string;
+    alt?: string;
+  } | null;
+  isActive?: boolean;
+  displayOrder?: number;
+}
+export type CategoryUpdate = Partial<Omit<CategoryInput, 'slug'>>;
+export interface MerchantCategory extends CategoryInput {
+  _id: string;
+  slug: string;
+  parentPath?: string;
+  productCount?: number;
+}
+export interface MerchantCategoryTree extends MerchantCategory {
+  children: MerchantCategoryTree[];
+  totalProductCount: number;
+}
+export interface MerchantOrder extends StorefrontOrder {
+  _id: string;
+  customerSnapshot?: {
+    name: string;
+    phone?: string;
+    email?: string;
+  };
+  shippingAddress?: Address;
+  lines: Array<{
+    lineId: string;
+    quantity: number;
+    snapshot: {
+      name?: string;
+      sku?: string;
+    };
+    lineTotal?: Money;
+  }>;
+  paymentState?: {
+    chargeStatus: string;
+    totalCharged?: Money;
+  };
+}
+export type OrderCommand = {
+  action: 'confirm' | 'start_processing' | 'ship' | 'deliver';
+} | {
+  action: 'cancel';
+  reason: string;
+};
+export interface StoreSettings {
+  version: number | null;
+  currency: string;
+  deliveryChargeMinor: number;
+}
+export interface MerchantMedia {
+  _id: string;
+  folder: string;
+  size: number;
+  title?: string;
+  alt?: string;
+  createdAt?: string;
+  url: string;
+  filename: string;
+  mimeType?: string;
+  width?: number;
+  height?: number;
+  variants?: Array<{
+    name: string;
+    url: string;
+    width: number;
+    height: number;
+    mimeType: string;
+    size: number;
+  }>;
+}
+export interface IntegrationProvider {
+  service: string;
+  provider: string;
+  label: string;
+  oauth: boolean;
+  credentialFields: Array<{
+    name: string;
+    label: string;
+    type: 'text' | 'password' | 'number' | 'boolean' | 'select';
+    required: boolean;
+    secret?: boolean;
+    placeholder?: string;
+    help?: string;
+    options?: Array<{
+      label: string;
+      value: string;
+    }>;
+  }>;
+}
+export interface MerchantIntegration {
+  _id: string;
+  service: string;
+  provider: string;
+  label?: string;
+  enabled: boolean;
+  status: 'connected' | 'disabled' | 'error';
+  config: Record<string, unknown>;
+  secretsSet: Record<string, boolean>;
+  lastTestedAt?: string | null;
+  lastTestStatus?: 'ok' | 'failed' | 'skipped';
+}
+export interface NotificationDelivery {
+  _id: string;
+  timestamp: string;
+  event: string;
+  status: 'delivered' | 'partial' | 'failed' | 'skipped';
+  subject?: {
+    sourceModel: string;
+    sourceId: string;
+  };
+}
+export interface MerchantApiKey {
+  id: string;
+  kind: 'user' | 'service';
+  name: string;
+  prefix: string;
+  ownerId: string;
+  scopes: string[];
+  status: 'active' | 'expired' | 'revoked';
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  ceilingRole: string | null;
+}
+export interface ApiKeyOptions {
+  scopes: Array<{
+    scope: string;
+    requires: string[];
+    grantable: boolean;
+  }>;
+  ceilingRoles: Array<{
+    role: string;
+    scopes: string[];
+  }>;
+  can: {
+    own: boolean;
+    createService: boolean;
+    readBranch: boolean;
+    updateService: boolean;
+    deleteOthers: boolean;
+  };
+  lifetime: {
+    defaultDays: number;
+    maxDays: number;
+    allowNeverExpires?: boolean;
+  };
+}
+export interface ApiKeyInput {
+  kind: 'user' | 'service';
+  name: string;
+  scopes: string[];
+  /** Null explicitly requests a key that does not expire. */
+  expiresInDays: number | null;
+  ceilingRole?: string;
+}
+export interface IssuedApiKey {
+  key: string;
+  record: MerchantApiKey;
+}
+/** Inclusive start and exclusive end as ISO timestamps, at most 92 days apart. */
+export interface AnalyticsWindow {
+  from: string;
+  to: string;
+}
+/** Order values include delivery charges and are independent of payment collection. */
+export interface MerchantOverview {
+  summary: {
+    totalOrders: number;
+    totalOrderValue: number;
+    fulfilledOrders: number;
+    fulfilledOrderValue: number;
+    canceledOrders: number;
+    canceledOrderValue: number;
+    averageOrderValue: number;
+  };
+  statuses: Array<{
+    status: string;
+    count: number;
+    orderValue: number;
+  }>;
+}
+//#endregion

package/dist/management-types.js

@@ -0,0 +1 @@
+export {};