@classytic/commerce-client 0.0.0-stage → 0.1.1

package/dist/management.d.ts

@@ -0,0 +1,100 @@
+import { DeliveryDistrict, DeliverySettings, DeliverySettingsUpdate } from "./delivery-types.js";
+import { AnalyticsWindow, ApiKeyInput, ApiKeyOptions, CategoryInput, IntegrationProvider, IssuedApiKey, MerchantApiKey, MerchantCategory, MerchantCategoryTree, MerchantIntegration, MerchantMedia, MerchantOrder, MerchantOverview, MerchantProduct, NotificationDelivery, OrderCommand, ProductInput, StoreSettings } from "./management-types.js";
+import { BaseApi } from "@classytic/arc-next/api";
+import { ArcClientConfig } from "@classytic/arc-next/client";
+//#region src/management.d.ts
+export interface MerchantClientOptions {
+  apiUrl: string;
+  token: string;
+  organizationId: string;
+  fetch?: ArcClientConfig['fetch'];
+}
+/** Capture one authenticated store; callers create a new instance when switching stores. */
+export declare function createMerchantClient(options: MerchantClientOptions): {
+  integrations: {
+    catalog: (signal?: AbortSignal) => Promise<IntegrationProvider[]>;
+    list: (signal?: AbortSignal) => Promise<MerchantIntegration[]>;
+    connect: (data: {
+      service: string;
+      provider: string;
+      label: string;
+      credentials: Record<string, unknown>;
+      enable: boolean;
+    }) => Promise<MerchantIntegration>;
+    command: (id: string, action: 'test' | 'enable' | 'disable') => Promise<MerchantIntegration>;
+    remove: (id: string) => Promise<null>;
+  };
+  notifications: {
+    list: ({ token, organizationId, params, options }?: {
+      token?: string | null;
+      organizationId?: string | null;
+      params?: import("@classytic/arc-next/api").QueryParams;
+      options?: Omit<import("@classytic/arc-next/api").RequestOptions, "token" | "organizationId">;
+    }) => Promise<import("@classytic/repo-core/pagination").PaginatedResult<NotificationDelivery>>;
+  };
+  apiKeys: {
+    options: (signal?: AbortSignal) => Promise<ApiKeyOptions>;
+    list: (owner: 'me' | 'branch', signal?: AbortSignal) => Promise<MerchantApiKey[]>;
+    create: (data: ApiKeyInput) => Promise<IssuedApiKey>;
+    rotate: (id: string) => Promise<IssuedApiKey>;
+    revoke: (id: string) => Promise<MerchantApiKey>;
+  };
+  delivery: {
+    read: (signal?: AbortSignal) => Promise<DeliverySettings>;
+    update: (data: DeliverySettingsUpdate) => Promise<DeliverySettings>;
+    districts(signal?: AbortSignal): Promise<DeliveryDistrict[]>;
+  };
+  products: BaseApi<MerchantProduct, ProductInput, Partial<ProductInput>>;
+  categories: BaseApi<MerchantCategory, CategoryInput, Partial<Omit<CategoryInput, "slug">>> & {
+    tree: (options?: {
+      signal?: AbortSignal;
+    }) => Promise<MerchantCategoryTree[]>;
+  };
+  analytics: {
+    overview(window: AnalyticsWindow, options?: {
+      signal?: AbortSignal;
+    }): Promise<MerchantOverview>;
+  };
+  orders: {
+    collect(id: string, amount: number, idempotencyKey: string): Promise<{
+      outstanding: number;
+      settled: boolean;
+      transactionId?: string;
+    }>;
+    list: ({ token, organizationId, params, options }?: {
+      token?: string | null;
+      organizationId?: string | null;
+      params?: import("@classytic/arc-next/api").QueryParams;
+      options?: Omit<import("@classytic/arc-next/api").RequestOptions, "token" | "organizationId">;
+    }) => Promise<import("@classytic/repo-core/pagination").PaginatedResult<MerchantOrder>>;
+    detail: (orderNumber: string, options?: {
+      signal?: AbortSignal;
+    }) => Promise<MerchantOrder>;
+    command(id: string, command: OrderCommand, idempotencyKey: string): Promise<MerchantOrder>;
+  };
+  settings: {
+    get: () => Promise<StoreSettings>;
+    update: (data: {
+      expectedVersion: number | null;
+      deliveryChargeMinor: number;
+    }) => Promise<StoreSettings>;
+  };
+  media: {
+    list: ({ token, organizationId, params, options }?: {
+      token?: string | null;
+      organizationId?: string | null;
+      params?: import("@classytic/arc-next/api").QueryParams;
+      options?: Omit<import("@classytic/arc-next/api").RequestOptions, "token" | "organizationId">;
+    }) => Promise<import("@classytic/repo-core/pagination").PaginatedResult<MerchantMedia>>;
+    remove: ({ token, organizationId, id, options }: {
+      token?: string | null;
+      organizationId?: string | null;
+      id: string;
+      options?: Omit<import("@classytic/arc-next/api").RequestOptions, "token" | "organizationId">;
+    }) => Promise<import("@classytic/repo-core/repository").DeleteResult>;
+    upload: (file: File, folder?: 'products' | 'categories') => Promise<MerchantMedia>;
+    uploadImage(file: File, folder?: 'products' | 'categories'): Promise<MerchantMedia>;
+  };
+};
+export type MerchantClient = ReturnType<typeof createMerchantClient>;
+//#endregion

package/dist/management.js

@@ -0,0 +1,265 @@
+import { BaseApi } from "@classytic/arc-next/api";
+import { createClient } from "@classytic/arc-next/client";
+//#region src/management-delivery.ts
+function createMerchantDelivery(client) {
+	const api = new BaseApi("stores/delivery", {
+		client,
+		basePath: "",
+		cache: "no-store"
+	});
+	return { delivery: {
+		read: (signal) => api.request("GET", `${api.baseUrl}/current`, { options: { signal } }),
+		update: (data) => api.request("PATCH", `${api.baseUrl}/current`, { data }),
+		async districts(signal) {
+			return (await api.request("GET", `${api.baseUrl}/districts`, { options: { signal } })).data;
+		}
+	} };
+}
+//#endregion
+//#region src/management-access.ts
+function key(value) {
+	if (!value || value === "." || value === "..") throw new Error("An identifier is required.");
+	return encodeURIComponent(value);
+}
+function createMerchantAccess(client) {
+	const config = {
+		client,
+		basePath: "",
+		cache: "no-store"
+	};
+	const integrations = new BaseApi("integrations", config);
+	const apiKeys = new BaseApi("auth/api-keys", config);
+	const deliveries = new BaseApi("notifications/delivery-log", config);
+	return {
+		integrations: {
+			catalog: (signal) => integrations.request("GET", `${integrations.baseUrl}/catalog`, { options: { signal } }),
+			list: (signal) => integrations.request("GET", integrations.baseUrl, { options: { signal } }),
+			connect: (data) => integrations.request("POST", integrations.baseUrl, { data }),
+			command: (id, action) => integrations.dispatchAction({
+				id: key(id),
+				action
+			}),
+			remove: (id) => integrations.request("DELETE", `${integrations.baseUrl}/${key(id)}`)
+		},
+		notifications: { list: deliveries.getAll.bind(deliveries) },
+		apiKeys: {
+			options: (signal) => apiKeys.request("GET", `${apiKeys.baseUrl}/options`, { options: { signal } }),
+			list: (owner, signal) => apiKeys.request("GET", apiKeys.baseUrl, {
+				params: { owner },
+				options: { signal }
+			}),
+			create: (data) => apiKeys.request("POST", apiKeys.baseUrl, { data }),
+			rotate: (id) => apiKeys.dispatchAction({
+				id: key(id),
+				action: "rotate"
+			}),
+			revoke: (id) => apiKeys.dispatchAction({
+				id: key(id),
+				action: "revoke"
+			})
+		}
+	};
+}
+//#endregion
+//#region src/management-media.ts
+function createMerchantMedia(client, fetcher) {
+	const media = new BaseApi("media", {
+		client,
+		basePath: "",
+		cache: "no-store"
+	});
+	async function put(target, blob) {
+		const headers = new Headers(target.headers);
+		if (!headers.has("content-type")) headers.set("content-type", blob.type);
+		if (!(await (fetcher ?? fetch)(target.uploadUrl, {
+			method: "PUT",
+			credentials: "omit",
+			headers,
+			signal: AbortSignal.timeout(6e4),
+			body: blob
+		})).ok) throw new Error("Image upload failed. Please retry.");
+	}
+	async function upload(file, folder, processed, originalFilename) {
+		const derivatives = processed?.derivatives ?? [];
+		const started = await media.request("POST", `${media.baseUrl}/start-write`, { data: {
+			filename: file.name,
+			contentType: file.type,
+			size: file.size,
+			folder,
+			...derivatives.length ? { derivatives: derivatives.map((item) => ({
+				name: item.name,
+				contentType: item.blob.type,
+				size: item.bytes
+			})) } : {}
+		} });
+		if (started.kind === "dedup") return started.media;
+		if (started.kind !== "presigned") throw new Error("Choose a smaller product image for direct upload.");
+		const targets = derivatives.map((derivative) => {
+			const target = started.derivativeUploads?.find((item) => item.name === derivative.name)?.upload;
+			if (!target) throw new Error("The server did not provide every requested image size. Please retry.");
+			return {
+				derivative,
+				target
+			};
+		});
+		await put(started.upload, file);
+		await Promise.all(targets.map(({ derivative, target }) => put(target, derivative.blob)));
+		const hints = processed ? (await import("@classytic/media-transform/image/uploadHints")).toUploadHints(processed) : {};
+		return media.request("POST", `${media.baseUrl}/complete-write`, { data: {
+			key: started.upload.key,
+			filename: file.name,
+			mimeType: file.type,
+			size: file.size,
+			...originalFilename ? { originalFilename } : {},
+			...hints,
+			...targets.length ? { variants: targets.map(({ derivative, target }) => ({
+				name: derivative.name,
+				key: target.key,
+				mimeType: derivative.blob.type,
+				size: derivative.bytes,
+				width: derivative.width,
+				height: derivative.height
+			})) } : {}
+		} });
+	}
+	return {
+		list: media.getAll.bind(media),
+		remove: media.delete.bind(media),
+		upload: (file, folder = "products") => upload(file, folder),
+		async uploadImage(file, folder = "products") {
+			const policy = await media.request("GET", `${media.baseUrl}/transform-policy`);
+			const { resolveTransformPlan, isTransformableImage } = await import("@classytic/media-transform/policy");
+			if (!isTransformableImage(file.type)) throw new Error("Choose a JPEG, PNG, WebP, AVIF or BMP image that your browser can open.");
+			const plan = resolveTransformPlan({
+				folder,
+				mimeType: file.type,
+				bytes: file.size
+			}, policy);
+			if (!plan.transform) {
+				if (plan.outcome === "preserve") return upload(file, folder);
+				throw new Error("The image processing policy is unsupported. Refresh the dashboard before uploading.");
+			}
+			const [{ createBrowserImageAdapter }, { compressImageSet }, { storedFilename }] = await Promise.all([
+				import("@classytic/media-transform/image/BrowserImageAdapter"),
+				import("@classytic/media-transform/image/compressImageSet"),
+				import("@classytic/media-transform/image/uploadHints")
+			]);
+			const result = await compressImageSet(await createBrowserImageAdapter(), file, plan.options).catch(() => {
+				throw new Error("Your browser could not process this image. Try a JPEG or PNG copy.");
+			});
+			return upload(new File([result.blob], storedFilename(file.name, result.format), { type: result.blob.type }), folder, result, file.name);
+		}
+	};
+}
+//#endregion
+//#region src/management.ts
+function orderKey(value) {
+	if (!value || value === "." || value === "..") throw new Error("An order number is required.");
+	return encodeURIComponent(value);
+}
+/** Capture one authenticated store; callers create a new instance when switching stores. */
+function createMerchantClient(options) {
+	const { token, organizationId, fetch: fetcher } = options;
+	const url = new URL(options.apiUrl);
+	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error("A valid HTTP(S) API mount is required.");
+	if (!token.trim() || !organizationId.trim()) throw new Error("A bearer token and organizationId are required.");
+	const client = createClient({
+		baseUrl: url.href.replace(/\/+$/, ""),
+		getToken: () => token,
+		getOrgId: () => organizationId,
+		credentials: "omit",
+		autoIdempotency: false,
+		timeoutMs: 15e3,
+		...fetcher ? { fetch: fetcher } : {}
+	});
+	const config = {
+		client,
+		basePath: "",
+		cache: "no-store"
+	};
+	const products = new BaseApi("products", config);
+	const categories = new BaseApi("categories", config);
+	const orders = new BaseApi("orders", config);
+	const stores = new BaseApi("stores", config);
+	return {
+		...createMerchantAccess(client),
+		...createMerchantDelivery(client),
+		products,
+		categories: Object.assign(categories, { tree: (options = {}) => categories.request("GET", `${categories.baseUrl}/tree`, { options }) }),
+		analytics: { async overview(window, options = {}) {
+			const from = new Date(window.from);
+			const to = new Date(window.to);
+			if (!Number.isFinite(from.getTime()) || !Number.isFinite(to.getTime()) || to <= from || to.getTime() - from.getTime() > 79488e5) throw new Error("Choose a valid analytics window of at most 92 days.");
+			const statuses = (await orders.request("GET", `${orders.baseUrl}/aggregations/revenueByStatus`, {
+				params: {
+					"createdAt[gte]": from.toISOString(),
+					"createdAt[lt]": to.toISOString()
+				},
+				options
+			})).rows.map(({ status, count, revenue }) => ({
+				status,
+				count,
+				orderValue: revenue
+			}));
+			const summary = {
+				totalOrders: 0,
+				totalOrderValue: 0,
+				fulfilledOrders: 0,
+				fulfilledOrderValue: 0,
+				canceledOrders: 0,
+				canceledOrderValue: 0,
+				averageOrderValue: 0
+			};
+			for (const row of statuses) {
+				summary.totalOrders += row.count;
+				summary.totalOrderValue += row.orderValue;
+				if (row.status === "fulfilled" || row.status === "completed") {
+					summary.fulfilledOrders += row.count;
+					summary.fulfilledOrderValue += row.orderValue;
+				}
+				if (row.status === "canceled") {
+					summary.canceledOrders += row.count;
+					summary.canceledOrderValue += row.orderValue;
+				}
+			}
+			summary.averageOrderValue = summary.totalOrders ? Math.round(summary.totalOrderValue / summary.totalOrders) : 0;
+			return {
+				summary,
+				statuses
+			};
+		} },
+		orders: {
+			collect(id, amount, idempotencyKey) {
+				if (!idempotencyKey.trim()) throw new Error("Preserve an explicit idempotencyKey for collection retries.");
+				return orders.dispatchAction({
+					id: orderKey(id),
+					action: "collect_payment",
+					data: { amount },
+					options: { headerOptions: { "Idempotency-Key": idempotencyKey } }
+				});
+			},
+			list: orders.getAll.bind(orders),
+			detail: (orderNumber, options = {}) => orders.getById({
+				id: orderKey(orderNumber),
+				options
+			}),
+			command(id, command, idempotencyKey) {
+				if (!idempotencyKey.trim()) throw new Error("Preserve an explicit idempotencyKey for command retries.");
+				const { action, ...data } = command;
+				return orders.dispatchAction({
+					id: orderKey(id),
+					action,
+					data,
+					options: { headerOptions: { "Idempotency-Key": idempotencyKey } }
+				});
+			}
+		},
+		settings: {
+			get: () => stores.request("GET", `${stores.baseUrl}/settings/current`),
+			update: (data) => stores.request("PATCH", `${stores.baseUrl}/settings/current`, { data })
+		},
+		media: createMerchantMedia(client, fetcher)
+	};
+}
+//#endregion
+export { createMerchantClient };

package/dist/platform.d.ts

@@ -0,0 +1,36 @@
+//#region src/platform.d.ts
+export type OrganizationStatus = 'pending' | 'active' | 'rejected' | 'suspended';
+export type OrganizationAction = 'approve' | 'reject' | 'suspend' | 'reactivate';
+export interface PlatformOrganization {
+  _id: string;
+  name: string;
+  slug: string;
+  status: OrganizationStatus;
+  createdAt?: string;
+  statusHistory?: Array<{
+    status: OrganizationStatus;
+    occurredAt: string;
+    by?: string;
+    note?: string;
+  }>;
+}
+/** Platform administration uses a bearer identity without selecting a merchant organization. */
+export declare function createPlatformClient({ apiUrl, token }: {
+  apiUrl: string;
+  token: string;
+}): {
+  organizations: {
+    list: ({ token, organizationId, params, options }?: {
+      token?: string | null;
+      organizationId?: string | null;
+      params?: import("@classytic/arc-next/api").QueryParams;
+      options?: Omit<import("@classytic/arc-next/api").RequestOptions, "token" | "organizationId">;
+    }) => Promise<import("@classytic/repo-core/pagination").PaginatedResult<PlatformOrganization>>;
+    decide(id: string, data: {
+      action: OrganizationAction;
+      expectedStatus: OrganizationStatus;
+      note: string;
+    }): Promise<PlatformOrganization>;
+  };
+};
+//#endregion

package/dist/platform.js

@@ -0,0 +1,29 @@
+import { BaseApi } from "@classytic/arc-next/api";
+import { createClient } from "@classytic/arc-next/client";
+//#region src/platform.ts
+/** Platform administration uses a bearer identity without selecting a merchant organization. */
+function createPlatformClient({ apiUrl, token }) {
+	if (!token.trim()) throw new Error("A platform bearer token is required.");
+	const url = new URL(apiUrl);
+	if (url.username || url.password || url.search || url.hash) throw new Error("Use a plain API URL.");
+	const client = createClient({
+		baseUrl: url.href.replace(/\/+$/, ""),
+		getToken: () => token,
+		credentials: "omit",
+		autoIdempotency: false,
+		timeoutMs: 15e3
+	});
+	const organizations = new BaseApi("admin/organizations", {
+		client,
+		basePath: "",
+		cache: "no-store"
+	});
+	return { organizations: {
+		list: organizations.getAll.bind(organizations),
+		decide(id, data) {
+			return organizations.request("POST", `${organizations.baseUrl}/${encodeURIComponent(id)}/action`, { data });
+		}
+	} };
+}
+//#endregion
+export { createPlatformClient };

package/dist/types-C0cSi6Pk.d.ts

@@ -0,0 +1,128 @@
+import { Address } from "@classytic/primitives/address";
+import { Money } from "@classytic/primitives/money";
+//#region src/types.d.ts
+/** Public wire projections; merchant-only catalog and buyer fields are absent. */
+interface StorefrontProduct {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string;
+  categorySlug?: string;
+  tags?: string[];
+  collections?: string[];
+  onSale?: boolean;
+  images?: Array<{
+    url: string;
+    alt?: string;
+    order?: number;
+    isFeatured?: boolean;
+    variants?: {
+      thumbnail?: string;
+      medium?: string;
+    };
+  }>;
+  monetization?: {
+    type: 'one_time';
+    basePrice: Money;
+    compareAtPrice?: Money;
+  };
+  variants?: Array<{
+    sku: string;
+    attributes: Record<string, string>;
+    priceModifier: number;
+  }>;
+}
+interface StorefrontCategory {
+  id: string;
+  name: string;
+  slug: string;
+  parent?: string | null;
+  parentPath?: string;
+  description?: string;
+  image?: {
+    url: string;
+    alt?: string;
+  } | null;
+  displayOrder?: number;
+}
+interface StorefrontProductPage {
+  data: StorefrontProduct[];
+  next: string | null;
+}
+interface StorefrontProductQuery {
+  limit?: number;
+  /** Opaque cursor returned by the preceding page; keep filters and sort unchanged. */
+  after?: string;
+  category?: string;
+  q?: string;
+  tag?: string;
+  collection?: string;
+  onSale?: boolean;
+  /** Inclusive base-price bounds in the store currency's integer minor units. */
+  minPrice?: number;
+  maxPrice?: number;
+  sort?: 'newest' | 'price-asc' | 'price-desc';
+}
+interface StorefrontProfile {
+  organizationId: string;
+  name: string;
+  slug: string;
+  status: 'active';
+  currency: string;
+  deliveryChargeMinor: number;
+}
+interface GuestCheckoutInput {
+  lines: Array<{
+    productId: string;
+    variantSku?: string;
+    quantity: number;
+  }>;
+  customer: {
+    name: string;
+    phone: string;
+    email?: string;
+  };
+  shippingAddress: Address & {
+    areaId?: number;
+  };
+}
+interface StorefrontOrder {
+  orderNumber: string;
+  status: string;
+  fulfillmentStatus?: 'unfulfilled' | 'partial' | 'fulfilled' | 'returned';
+  fulfillmentSummary?: {
+    total: number;
+    fulfilled: number;
+    shipped: number;
+    delivered: number;
+    returned: number;
+  };
+  paymentTerm?: 'prepaid' | 'collect_on_delivery';
+  currency: string;
+  totals: {
+    subtotal: Money;
+    discount: Money;
+    tax: Money;
+    shipping: Money;
+    grandTotal: Money;
+    taxBasis?: 'inclusive' | 'exclusive';
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+type GuestCheckoutResult = StorefrontOrder & {
+  accessToken: string;
+};
+interface GuestOrderAccess {
+  orderNumber: string;
+  accessToken: string;
+}
+interface StorefrontRequestOptions {
+  signal?: AbortSignal;
+}
+interface GuestCheckoutOptions extends StorefrontRequestOptions {
+  /** Create once per checkout attempt; preserve across retries and lost responses. */
+  idempotencyKey: string;
+}
+//#endregion
+export { StorefrontCategory as a, StorefrontProductPage as c, StorefrontRequestOptions as d, GuestOrderAccess as i, StorefrontProductQuery as l, GuestCheckoutOptions as n, StorefrontOrder as o, GuestCheckoutResult as r, StorefrontProduct as s, GuestCheckoutInput as t, StorefrontProfile as u };

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+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";
+export { GuestCheckoutInput, GuestCheckoutOptions, GuestCheckoutResult, GuestOrderAccess, StorefrontCategory, StorefrontOrder, StorefrontProduct, StorefrontProductPage, StorefrontProductQuery, StorefrontProfile, StorefrontRequestOptions };

package/dist/types.js

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

package/management.md

@@ -0,0 +1,100 @@
+# Merchant client
+
+Import `createMerchantClient` from `@classytic/commerce-client/management`.
+Its contracts live in `/management/types`. The guest-only root entry imports
+none of this authenticated surface.
+
+```ts
+import { createMerchantClient } from '@classytic/commerce-client/management';
+
+const merchant = createMerchantClient({
+  apiUrl: 'https://api.example.com/api/v1',
+  token: merchantSessionToken,
+  organizationId: selectedStoreId,
+});
+const products = await merchant.products.getAll({ params: { page: 1, limit: 20 } });
+const categories = await merchant.categories.tree();
+const orders = await merchant.orders.list();
+```
+
+Each instance captures one bearer credential and store. Create another instance
+on session or store changes. Cookies and automatic command keys are disabled.
+The server authorizes every operation; choosing a store ID grants no access.
+
+Product/category APIs use Arc Next's typed CRUD methods. Order writes expose
+only supported commands (`confirm`, `start_processing`, `ship`, `deliver`,
+`cancel`) and cash collection. Generate a key once per command attempt and keep
+it, its amount and its body unchanged across retries.
+
+```ts
+const key = crypto.randomUUID();
+await merchant.orders.command(orderNumber, { action: 'confirm' }, key);
+
+// After complete delivery and actual receipt of cash, with the collect permission:
+const collectionKey = crypto.randomUUID();
+await merchant.orders.collect(orderNumber, amountMinor, collectionKey);
+```
+
+`media.upload(file)` uses the shared start-write → storage PUT → complete-write
+protocol. Merchant authorization goes to the API; the storage PUT receives only
+its presigned headers and file bytes. A failed PUT does not confirm an upload.
+Settings updates carry `expectedVersion`; refetch after a conflict before saving.
+
+`integrations.catalog()` describes enabled providers and credential fields.
+`integrations.connect()` stores/tests a connection for the authenticated store;
+`command(id, 'test' | 'enable' | 'disable')` controls it and `remove(id)` disconnects
+it. `notifications.list()` reads paginated delivery evidence. These routes may be
+absent when the deployment has no notification credential encryption key.
+
+`apiKeys.options()` returns live scope grants, ownership permissions and lifetime
+bounds. Use them to construct `apiKeys.create(input)`. `apiKeys.list('me' | 'branch')`
+returns safe records; `rotate(id)` returns a replacement secret and `revoke(id)`
+disables one. Creation/rotation require a fresh bearer session. Store the returned
+secret on your server: it is shown once, cannot be read later and should never be
+placed in query caches or browser storage. These mutations have no automatic
+retry; refresh the key list after an uncertain outcome before retrying.
+
+`analytics.overview({ from, to }, { signal })` reads one store-scoped order
+aggregation. Supply ISO timestamps for an inclusive start and exclusive end,
+at most 92 days apart. Read the configured currency through `settings.get()`.
+Amounts are integer minor units; the rounded average uses the same unit.
+
+The summary reports order count/value, fulfilled count/value, canceled
+count/value and average order value, alongside the individual status rows.
+Total order value includes every status and delivery charges. Fulfilled combines
+`fulfilled` and `completed`: shipment can fulfill an order before delivery.
+Refunded remains a separate status. These metrics do not measure received cash
+or prove delivery. Order-read permission is required, including `read:orders`
+for API keys; organization IDs in query parameters cannot widen the store scope.
+
+## Category hierarchy
+
+`categories.tree({ signal })` returns nested categories with `children` and
+`totalProductCount`. `parent` is the parent category's slug; `null` moves a category
+to the top level. Slugs are permanent after creation. Omit a blank create slug to
+generate it from the name; update names without resending a slug.
+
+Import `categoryChoices` from `@classytic/commerce-client/category-tree` for
+breadcrumb labels. Pass the edited slug as its second argument to exclude that
+category and all its descendants from parent choices.
+
+`media.uploadImage(file, 'categories')` optimizes a category image using the
+category-folder policy. Send `image: null` to clear its reference; detached-media
+cleanup follows the server's normal governance policy.
+
+Product writes also accept `tags`, `collections` and
+`defaultMonetization.pricing.compareAtPrice`. The catalog derives `onSale`; clients
+never set it. Tags and collections use the existing catalog arrays, with no
+additional collection-management service.
+
+
+### Media library
+
+`client.media.list({ params: { page: 1, limit: 20, folder: 'products' } })`
+returns tenant-scoped media and pagination. `client.media.remove({ id })` uses
+the media resource's guarded delete; an in-use image is refused by the server.
+
+`client.media.uploadImage(file, folder)` resolves the server's transform policy
+through media-transform before requesting storage writes. The server must accept
+every output format in its policy, including the browser encoder's fallback.
+Passthrough thresholds and dimensions belong to that policy, rather than the UI.