@caldik/client 0.1.6 → 0.1.7

package/README.md

@@ -165,6 +165,10 @@ The following fields are omitted by default unless explicitly requested using `i
 
 ### Cart Management
 
+The SDK manages the `session` cookie and server persistence automatically. Cart
+requests, responses, and saved browser state do not require version numbers.
+Existing saved carts are restored automatically after upgrading.
+
 **Get the cart**
 
 Refresh the current items and applied discount from the server.
@@ -370,14 +374,89 @@ Omit `rememberMe` to use the default session duration.
 
 ### Session Check
 
-Retrieve the current customer's authentication status, account details, and session expiration.
+Check whether the shopper is authenticated. HTTP 200 has no body and resolves to
+`undefined`; HTTP 401 rejects with `CaldikHttpError`. Customer details are returned
+by `me()`.
+
+```ts
+await caldik.customer.session()
+```
+
+### Current Customer
+
+**Get the signed-in customer**
+
+```ts
+const { customer } = await caldik.customers.me()
+console.log(customer.name, customer.email)
+```
+
+**List the customer's orders**
+
+```ts
+const { orders, nextCursor } = await caldik.customers.orders.list({ limit: 5 })
+```
+
+**Read the next page**
+
+```ts
+if (nextCursor) {
+  const nextPage = await caldik.customers.orders.list({ cursor: nextCursor })
+}
+```
+
+**Get one of the customer's orders**
 
 ```ts
-const {
-  authenticated,
-  customer,
-  expiresAt,
-} = await caldik.customer.session()
+const { order } = await caldik.customers.orders.get("ORDER_...")
+console.log(order.items)
+```
+
+**Get the customer's balance**
+
+```ts
+const { balance } = await caldik.customers.balance.get()
+console.log(balance.amount, balance.currency)
+```
+
+The default currency is the store's currency. Pass `{ currency: "USD" }` to read
+another balance. Amounts are decimal strings; a missing balance is `"0.00"`.
+
+### Batch Reads
+
+**Fetch several resources in one HTTP request**
+
+```ts
+const data = await caldik.batch({
+  customer: caldik.customers.me(),
+  orders: caldik.orders.list({ limit: 5 }),
+  balance: caldik.customers.balance.get(),
+  rank: caldik.plugins.loyalty.getRank(),
+})
+
+console.log(data.customer.customer.email)
+console.log(data.rank.rank?.name)
+```
+
+Batches accept up to 25 distinct, unstarted read requests from the same client.
+Build the requests in the batch expression; already awaited requests cannot be
+batched. Catalog reads and read-only plugin methods are also supported. Each
+result retains the same shape as an individual call, including `undefined` for
+a successful session check. Batches are independent reads, not a transaction.
+
+**Handle a partially failed batch**
+
+```ts
+import { CaldikBatchError } from "@caldik/client"
+
+try {
+  const data = await caldik.batch({ customer: caldik.customers.me() })
+} catch (error) {
+  if (error instanceof CaldikBatchError) {
+    console.log(error.errors) // HTTP status and response for each failed key
+    console.log(error.results) // successful results remain available
+  }
+}
 ```
 
 ### Password Reset

package/dist/development.d.mts

@@ -0,0 +1,17 @@
+//#region development/refresh-plugin-types.d.mts
+type PluginContractFetcher = (url: URL, options: RequestInit) => Promise<Response>;
+declare function refreshPluginTypes(options: {
+  storeId: string;
+  apiUrl?: string;
+  output?: string;
+  projectRoot?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  fetcher?: PluginContractFetcher;
+}): Promise<{
+  changed: boolean;
+  output: string;
+  types: string;
+}>;
+//#endregion
+export { type PluginContractFetcher, refreshPluginTypes };

package/dist/development.mjs

@@ -0,0 +1,153 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region development/plugin-types.mjs
+const types = /* @__PURE__ */ new Set([
+	"object",
+	"array",
+	"string",
+	"number",
+	"integer",
+	"boolean",
+	"null"
+]);
+const safeKey = (value) => typeof value === "string" && /^[a-zA-Z][a-zA-Z0-9_\-]{0,63}$/.test(value) && ![
+	"constructor",
+	"prototype",
+	"then"
+].includes(value);
+function schemaType(schema, depth = 0) {
+	if (depth > 8 || !schema || typeof schema !== "object" || Array.isArray(schema)) throw new Error("Invalid plugin type schema");
+	if (schema.enum) {
+		if (!Array.isArray(schema.enum) || !schema.enum.length || schema.enum.length > 64 || schema.enum.some((value) => value !== null && ![
+			"string",
+			"number",
+			"boolean"
+		].includes(typeof value))) throw new Error("Invalid plugin enum");
+		return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+	}
+	if (schema.anyOf) {
+		if (!Array.isArray(schema.anyOf) || !schema.anyOf.length || schema.anyOf.length > 8) throw new Error("Invalid plugin union");
+		return schema.anyOf.map((value) => `(${schemaType(value, depth + 1)})`).join(" | ");
+	}
+	if (!types.has(schema.type)) throw new Error("Unsupported plugin type");
+	if (schema.type === "array") return `Array<${schemaType(schema.items, depth + 1)}>`;
+	if (schema.type === "object") {
+		const properties = schema.properties ?? {};
+		if (!properties || typeof properties !== "object" || Array.isArray(properties) || Object.keys(properties).length > 32) throw new Error("Invalid plugin object");
+		const required = schema.required ?? [];
+		if (!Array.isArray(required) || !required.every((value) => typeof value === "string" && Object.hasOwn(properties, value))) throw new Error("Invalid required properties");
+		return `{ ${Object.entries(properties).map(([name, value]) => `${JSON.stringify(name)}${required.includes(name) ? "" : "?"}: ${schemaType(value, depth + 1)};`).join(" ")} }`;
+	}
+	return schema.type === "integer" ? "number" : schema.type;
+}
+function generatePluginTypes(metadata) {
+	if (!metadata || !Array.isArray(metadata.plugins) || metadata.plugins.length > 100) throw new Error("Invalid installed plugin metadata");
+	const names = /* @__PURE__ */ new Set();
+	const lines = [
+		"// Generated by Caldik. Plugin contracts refresh automatically during caldik dev.",
+		"import type { CaldikRequest } from \"@caldik/client\";",
+		"",
+		"declare module \"@caldik/client\" {",
+		"  interface CaldikPlugins {"
+	];
+	for (const plugin of [...metadata.plugins].sort((a, b) => String(a.namespace).localeCompare(String(b.namespace)))) {
+		if (!safeKey(plugin.namespace) || names.has(plugin.namespace) || !plugin.methods || typeof plugin.methods !== "object" || Array.isArray(plugin.methods) || Object.keys(plugin.methods).length > 16) throw new Error("Invalid plugin namespace");
+		names.add(plugin.namespace);
+		lines.push(`    readonly ${JSON.stringify(plugin.namespace)}: {`);
+		for (const [name, method] of Object.entries(plugin.methods).sort(([a], [b]) => a.localeCompare(b))) {
+			if (!safeKey(name) || !method || typeof method !== "object") throw new Error("Invalid plugin method");
+			const input = schemaType(method.input);
+			const output = schemaType(method.output);
+			const empty = method.input.type === "object" && !Object.keys(method.input.properties ?? {}).length;
+			const optional = method.input.type === "object" && !method.input.required?.length;
+			lines.push(`      readonly ${JSON.stringify(name)}: (${empty ? "" : `input${optional ? "?" : ""}: ${input}`}) => CaldikRequest<${output}>;`);
+		}
+		lines.push("    };");
+	}
+	lines.push("  }", "}", "");
+	return lines.join("\n");
+}
+const packageTypesPath = resolve(fileURLToPath(new URL("../", import.meta.url)), "types/plugins.d.ts");
+const generatedPrefix = "// Generated by Caldik.";
+async function readOptional(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return "";
+		throw error;
+	}
+}
+/** Replace the directory entry so Bun's hard-linked package cache is never modified. */
+async function writeGeneratedTypes(output, types) {
+	const previous = await readOptional(output);
+	if (previous && !previous.startsWith(generatedPrefix)) throw new Error("Output contains handwritten declarations; choose another output path");
+	if (previous === types) return false;
+	await mkdir(dirname(output), { recursive: true });
+	const temporary = `${output}.${randomUUID()}.tmp`;
+	try {
+		await writeFile(temporary, types, "utf8");
+		await rename(temporary, output);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+	return true;
+}
+async function responseText(response) {
+	const reader = response.body?.getReader();
+	if (!reader) throw new Error("Empty plugin contract response");
+	const chunks = [];
+	let bytes = 0;
+	try {
+		for (;;) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			bytes += value.byteLength;
+			if (bytes > 1048576) throw new Error("Plugin contracts exceed 1 MiB");
+			chunks.push(value);
+		}
+	} finally {
+		await reader.cancel().catch(() => void 0);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+async function refreshPluginTypes({ storeId, apiUrl = "https://api.caldik.com", output = packageTypesPath, projectRoot, signal, timeoutMs = 5e3, fetcher = fetch }) {
+	signal?.throwIfAborted();
+	if (typeof storeId !== "string" || !/^STORE_[a-f0-9]{32}$/i.test(storeId)) throw new Error("The development store ID is invalid");
+	const base = new URL(apiUrl);
+	if (!["https:", "http:"].includes(base.protocol) || base.username || base.password || base.search || base.hash) throw new Error("API URL must be an HTTP(S) base URL without credentials, query or fragment");
+	const url = new URL(`${base.href.replace(/\/+$/, "")}/v1/stores/${encodeURIComponent(storeId)}/plugins/sdk`);
+	output = resolve(output);
+	if (!output.endsWith(".d.ts")) throw new Error("Plugin types must use a .d.ts output path");
+	const writeTypes = async (types) => {
+		const changed = await writeGeneratedTypes(output, types);
+		if (projectRoot && output === packageTypesPath) {
+			const snapshot = resolve(projectRoot, await stat(resolve(projectRoot, "src")).then((value) => value.isDirectory()).catch(() => false) ? "src/caldik.plugins.d.ts" : "caldik.plugins.d.ts");
+			const current = await readOptional(snapshot);
+			if (!current || current.startsWith(generatedPrefix)) await writeGeneratedTypes(snapshot, types);
+		}
+		return changed;
+	};
+	const context = `// Context: ${createHash("sha256").update(url.href).digest("hex")}\n`;
+	const previous = await readOptional(output);
+	if (previous.startsWith(generatedPrefix) && previous.includes("// Context: ") && !previous.includes(context)) await writeTypes(generatePluginTypes({ plugins: [] }));
+	const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+	const response = await fetcher(url, {
+		signal: requestSignal,
+		credentials: "omit",
+		headers: { Accept: "application/json" }
+	});
+	if (!response.ok) throw new Error(`Plugin contract request failed (HTTP ${response.status})`);
+	const metadata = JSON.parse(await responseText(response));
+	if (metadata.success !== true || metadata.storeId !== storeId) throw new Error("The API returned invalid contracts or contracts for another store");
+	const types = generatePluginTypes(metadata).replace(/\n/, `\n${context}`);
+	requestSignal.throwIfAborted();
+	return {
+		changed: await writeTypes(types),
+		output,
+		types
+	};
+}
+//#endregion
+export { refreshPluginTypes };

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+/// <reference path="../types/plugins.d.ts" />
 //#region src/payment-providers.generated.d.ts
 declare const paymentProviderIds: readonly ["customer_balance", "stripe", "ovgc"];
 declare const checkoutPaymentProviderIds: readonly ["customer_balance", "stripe", "ovgc"];
@@ -200,9 +201,10 @@ interface StorefrontOrder {
   subtotal: string;
   amount: string;
   discount: {
-    code: string;
+    code: string | null;
     percentage: string;
     amount: string;
+    source: "code" | "loyalty";
   } | null;
   currency: string;
 }
@@ -294,15 +296,7 @@ interface CustomerEmailLoginInput {
   email: string;
   rememberMe?: boolean;
 }
-interface CustomerSessionResponse {
-  success: boolean;
-  authenticated: boolean;
-  customer: {
-    id: string;
-    email: string | null;
-  } | null;
-  expiresAt: number | null;
-}
+type CustomerSessionResponse = void;
 interface CustomerPasswordResetResponse extends CustomerLoginResponse {
   expiresAt: number;
   message: string;
@@ -330,14 +324,72 @@ interface CustomerProfileResponse {
   success: boolean;
   customer: {
     id: string;
+    shortId: string;
+    displayId: string;
+    name: string | null;
     email: string | null;
-    extensions?: Record<string, Record<string, string | number | boolean>>;
+    phone: string | null;
+    createdAt: number;
+    updatedAt: number;
+    extensions: Record<string, Record<string, string | number | boolean>>;
   };
-  balances: Array<{
+}
+interface CustomerBalanceResponse {
+  success: boolean;
+  balance: {
     currency: string;
     amount: string;
+  };
+}
+interface CustomerOrderListOptions {
+  limit?: number;
+  cursor?: string;
+}
+interface CustomerOrder {
+  id: string;
+  shortId: string;
+  displayId: string;
+  paymentStatus: string;
+  fulfillmentStatus: string;
+  amount: string;
+  subtotal: string;
+  currency: string;
+  createdAt: number;
+  updatedAt: number;
+  discount: {
+    code: string | null;
+    percentage: string;
+    amount: string;
+    source: "code" | "loyalty";
+  } | null;
+}
+interface CustomerOrderItem {
+  id: string;
+  productId: string | null;
+  productVariantId: string | null;
+  name: string;
+  description: string | null;
+  quantity: number;
+  unitAmount: string;
+  totalAmount: string;
+  customFields: Array<{
+    id: string;
+    name: string;
+    inputType: string;
+    value: string | number | boolean;
   }>;
 }
+interface CustomerOrdersResponse {
+  success: boolean;
+  orders: CustomerOrder[];
+  nextCursor: string | null;
+}
+interface CustomerOrderResponse {
+  success: boolean;
+  order: CustomerOrder & {
+    items: CustomerOrderItem[];
+  };
+}
 interface CustomerLoginSettings {
   passwordEnabled: boolean;
 }
@@ -373,6 +425,8 @@ interface CheckoutPaymentMethodsResponse {
 //#endregion
 //#region src/internal/types.d.ts
 interface RequestOptions {
+  /** Response intentionally has no JSON body. */
+  empty?: boolean;
   edgeCache?: boolean;
   /** Internal authorization policy. Protected hosted calls are the default. */
   access?: "public" | "runtime";
@@ -380,6 +434,29 @@ interface RequestOptions {
   headers?: Record<string, string>;
 }
 //#endregion
+//#region src/internal/request.d.ts
+interface RequestDescriptor {
+  method: "GET" | "POST";
+  path: string;
+  params?: Record<string, string | number>;
+  input?: unknown;
+  empty?: boolean;
+}
+/** Normal Promise scheduled on the next microtask so synchronous calls can join a batch. */
+declare class CaldikRequest<T> extends Promise<T> {
+  readonly owner: object;
+  readonly descriptor: RequestDescriptor;
+  static get [Symbol.species](): PromiseConstructor;
+  private dispatched;
+  private bound;
+  private resolveRequest;
+  private rejectRequest;
+  constructor(owner: object, descriptor: RequestDescriptor, execute: () => Promise<T>);
+  get started(): boolean;
+  cancel(error: unknown): void;
+  bind(promise: Promise<T>): void;
+}
+//#endregion
 //#region src/internal/client.d.ts
 type HttpClientOptions = {
   apiKey?: string;
@@ -388,6 +465,10 @@ type HttpClientOptions = {
   request?: Request;
   onSetCookie?: (cookie: string) => void | Promise<void>;
 };
+declare class CaldikHttpError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number);
+}
 declare class CaldikHttpClient {
   private readonly apiKey?;
   private readonly apiUrl;
@@ -404,59 +485,75 @@ declare class CaldikHttpClient {
   private captureCookies;
   private baseUrl;
   private request;
-  get<T>(path: string, params?: Record<string, string | number>, options?: RequestOptions): Promise<T>;
-  post<T>(path: string, input?: unknown, options?: RequestOptions): Promise<T>;
+  get<T>(path: string, params?: Record<string, string | number>, options?: RequestOptions): CaldikRequest<T>;
+  post<T>(path: string, input?: unknown, options?: RequestOptions): CaldikRequest<T>;
 }
 //#endregion
+//#region src/batch.d.ts
+type BatchInput = Record<string, CaldikRequest<any>>;
+type BatchResult<T extends BatchInput> = { [K in keyof T]: Awaited<T[K]> };
+declare class CaldikBatchError extends Error {
+  readonly results: Record<string, unknown>;
+  readonly errors: Record<string, {
+    status: number;
+    body: unknown;
+  }>;
+  constructor(results: Record<string, unknown>, errors: Record<string, {
+    status: number;
+    body: unknown;
+  }>);
+}
+declare function batchRequests<T extends BatchInput>(client: CaldikHttpClient, input: T): Promise<BatchResult<T>>;
+//#endregion
 //#region src/categories.d.ts
 declare class CategoriesApi {
   private client;
   constructor(client: CaldikHttpClient);
-  list(options?: number | CategoryListOptions): Promise<CategoriesResponse>;
-  get(categoryId: string): Promise<CategoryResponse>;
+  list(options?: number | CategoryListOptions): CaldikRequest<CategoriesResponse>;
+  get(categoryId: string): CaldikRequest<CategoryResponse>;
 }
 //#endregion
 //#region src/products.d.ts
 declare class ProductsApi {
   private client;
   constructor(client: CaldikHttpClient);
-  list(): Promise<ProductsResponse>;
-  get(productIdOrSlug: string, options?: ProductGetOptions): Promise<ProductResponse>;
+  list(): CaldikRequest<ProductsResponse>;
+  get(productIdOrSlug: string, options?: ProductGetOptions): CaldikRequest<ProductResponse>;
 }
 //#endregion
 //#region src/reviews.d.ts
 declare class ReviewsApi {
   private client;
   constructor(client: CaldikHttpClient);
-  list(limit?: number): Promise<ReviewsResponse>;
+  list(limit?: number): CaldikRequest<ReviewsResponse>;
 }
 //#endregion
 //#region src/store.d.ts
 declare class StoreApi {
   private client;
   constructor(client: CaldikHttpClient);
-  get(): Promise<StoreResponse>;
+  get(): CaldikRequest<StoreResponse>;
 }
 //#endregion
 //#region src/checkout.d.ts
 declare class CheckoutApi {
   private client;
   readonly paymentmethods: {
-    list: () => Promise<CheckoutPaymentMethodsResponse>;
+    list: () => CaldikRequest<CheckoutPaymentMethodsResponse>;
   };
   readonly settings: {
-    get: () => Promise<CheckoutSettingsResponse>;
+    get: () => CaldikRequest<CheckoutSettingsResponse>;
   };
   constructor(client: CaldikHttpClient);
-  create(input: CreateOrderInput): Promise<OrderResponse>;
-  payWithBalance(orderId: string): Promise<OrderResponse>;
+  create(input: CreateOrderInput): CaldikRequest<OrderResponse>;
+  payWithBalance(orderId: string): CaldikRequest<OrderResponse>;
 }
 //#endregion
 //#region src/customer.d.ts
 declare class CustomerApi {
   private client;
   readonly settings: {
-    get: () => Promise<CustomerLoginSettingsResponse>;
+    get: () => CaldikRequest<CustomerLoginSettingsResponse>;
   };
   readonly login: {
     (email: string, options?: {
@@ -477,18 +574,27 @@ declare class CustomerApi {
     requestReset: (email: string) => Promise<CustomerPasswordResetResponse>;
     reset: (input: CustomerPasswordResetInput) => Promise<CustomerPasswordResetVerifyResponse>;
   };
+  readonly orders: {
+    list: (options?: CustomerOrderListOptions) => CaldikRequest<CustomerOrdersResponse>;
+    get: (id: string) => CaldikRequest<CustomerOrderResponse>;
+  };
+  readonly balance: {
+    get: (options?: {
+      currency?: string;
+    }) => CaldikRequest<CustomerBalanceResponse>;
+  };
   constructor(client: CaldikHttpClient);
-  /** Check a store-scoped session without raising an error for signed-out customers. */
-  session(): Promise<CustomerSessionResponse>;
-  /** Read the signed-in customer and their balances. */
-  me(): Promise<CustomerProfileResponse>;
+  /** Resolves without a body on HTTP 200; rejects with status 401 when signed out. */
+  session(): CaldikRequest<void>;
+  /** Read the signed-in customer's profile. */
+  me(): CaldikRequest<CustomerProfileResponse>;
 }
 //#endregion
 //#region src/subscriptions.d.ts
 declare class SubscriptionsApi {
   private client;
   constructor(client: CaldikHttpClient);
-  create(input: CreateSubscriptionInput): Promise<SubscriptionResponse>;
+  create(input: CreateSubscriptionInput): CaldikRequest<SubscriptionResponse>;
 }
 //#endregion
 //#region src/discounts.d.ts
@@ -511,7 +617,7 @@ interface DiscountQuoteResponse {
 declare class DiscountsApi {
   private client;
   constructor(client: CaldikHttpClient);
-  check(input: CheckDiscountInput): Promise<DiscountQuoteResponse>;
+  check(input: CheckDiscountInput): CaldikRequest<DiscountQuoteResponse>;
 }
 //#endregion
 //#region src/cart.d.ts
@@ -549,7 +655,7 @@ declare class CartApi {
   private resolve;
   private reset;
   private mutate;
-  private save;
+  private saveDiscount;
   private quote;
   get(): Promise<CartSnapshot>;
   add(item: ProductCommerceItem): Promise<CartSnapshot>;
@@ -563,6 +669,8 @@ declare class CartApi {
 }
 //#endregion
 //#region src/index.d.ts
+/** Populated automatically from the store's plugin contracts during caldik dev. */
+interface CaldikPlugins {}
 interface CaldikClientOptions {
   /** Store ID override for external servers or local browser development. */
   storeId?: string;
@@ -581,10 +689,18 @@ declare class CaldikClient {
   readonly store: StoreApi;
   readonly checkout: CheckoutApi;
   readonly customer: CustomerApi;
+  readonly customers: CustomerApi;
+  readonly orders: {
+    list: (options?: CustomerOrderListOptions) => CaldikRequest<CustomerOrdersResponse>;
+    get: (id: string) => CaldikRequest<CustomerOrderResponse>;
+  };
+  readonly plugins: CaldikPlugins;
   readonly subscriptions: SubscriptionsApi;
   readonly discounts: DiscountsApi;
   readonly cart: CartApi;
+  private readonly client;
   constructor(options?: CaldikClientOptions);
+  batch<T extends BatchInput>(input: T): Promise<BatchResult<T>>;
 }
 //#endregion
-export { AppliedDiscount, CaldikClient, CaldikClientOptions, CartApi, CartCheckoutInput, CartDiscount, CartItem, CartSnapshot, CategoriesResponse, Category, CategoryDetails, CategoryInclude, CategoryListOptions, CategoryMetadata, CategoryProduct, CategoryResponse, CheckDiscountInput, CheckoutPayment, CheckoutPaymentMethod, CheckoutPaymentMethodsResponse, CheckoutPaymentProviderId, CheckoutSettings, CheckoutSettingsResponse, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerEmailLoginInput, CustomerLoginResponse, CustomerLoginSettings, CustomerLoginSettingsResponse, CustomerLoginVerifyResponse, CustomerPasswordInput, CustomerPasswordResetInput, CustomerPasswordResetResponse, CustomerPasswordResetVerifyResponse, CustomerPasswordResponse, CustomerProfileResponse, CustomerRegistrationInput, CustomerRegistrationResponse, CustomerSessionResponse, DiscountQuoteResponse, DiscountsApi, ManualCommerceItem, OrderResponse, PaymentProviderId, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductGetOptions, ProductImage, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreSocials, StoreWebhookEvent, StoreWebhookEventName, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };
+export { AppliedDiscount, BatchInput, BatchResult, CaldikBatchError, CaldikClient, CaldikClientOptions, CaldikHttpError, CaldikPlugins, CaldikRequest, CartApi, CartCheckoutInput, CartDiscount, CartItem, CartSnapshot, CategoriesResponse, Category, CategoryDetails, CategoryInclude, CategoryListOptions, CategoryMetadata, CategoryProduct, CategoryResponse, CheckDiscountInput, CheckoutPayment, CheckoutPaymentMethod, CheckoutPaymentMethodsResponse, CheckoutPaymentProviderId, CheckoutSettings, CheckoutSettingsResponse, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerBalanceResponse, CustomerEmailLoginInput, CustomerLoginResponse, CustomerLoginSettings, CustomerLoginSettingsResponse, CustomerLoginVerifyResponse, CustomerOrder, CustomerOrderItem, CustomerOrderListOptions, CustomerOrderResponse, CustomerOrdersResponse, CustomerPasswordInput, CustomerPasswordResetInput, CustomerPasswordResetResponse, CustomerPasswordResetVerifyResponse, CustomerPasswordResponse, CustomerProfileResponse, CustomerRegistrationInput, CustomerRegistrationResponse, CustomerSessionResponse, DiscountQuoteResponse, DiscountsApi, ManualCommerceItem, OrderResponse, PaymentProviderId, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductGetOptions, ProductImage, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreSocials, StoreWebhookEvent, StoreWebhookEventName, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, batchRequests, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };

package/dist/index.mjs

@@ -23,6 +23,56 @@ function defaultApiUrl(browser) {
 	return environmentApiUrl(browser) || (typeof API_URL !== "undefined" ? API_URL : "https://api.caldik.com");
 }
 //#endregion
+//#region src/internal/request.ts
+/** Normal Promise scheduled on the next microtask so synchronous calls can join a batch. */
+var CaldikRequest = class extends Promise {
+	owner;
+	descriptor;
+	static get [Symbol.species]() {
+		return Promise;
+	}
+	dispatched = false;
+	bound = false;
+	resolveRequest;
+	rejectRequest;
+	constructor(owner, descriptor, execute) {
+		let resolve;
+		let reject;
+		super((yes, no) => {
+			resolve = yes;
+			reject = no;
+		});
+		this.owner = owner;
+		this.descriptor = descriptor;
+		this.resolveRequest = resolve;
+		this.rejectRequest = reject;
+		queueMicrotask(() => {
+			if (this.bound) return;
+			this.dispatched = true;
+			try {
+				execute().then(resolve, reject);
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+	get started() {
+		return this.dispatched || this.bound;
+	}
+	cancel(error) {
+		if (this.started) return;
+		this.bound = true;
+		this.rejectRequest(error);
+		this.catch(() => void 0);
+	}
+	bind(promise) {
+		if (this.started) throw new Error("An already started request cannot be batched");
+		this.bound = true;
+		promise.then(this.resolveRequest, this.rejectRequest);
+		this.catch(() => void 0);
+	}
+};
+//#endregion
 //#region src/internal/client.ts
 const STORE_ID_PATTERN = /^STORE_[a-f0-9]{32}$/i;
 const STOREFRONT_STORE_ID_ATTRIBUTE = "data-caldik-store-id";
@@ -74,6 +124,7 @@ var CaldikHttpClient = class {
 		return this.storeId || boundRuntimeStoreId();
 	}
 	hasCartSession() {
+		if (this.cookies.has("session")) return true;
 		const prefix = `caldik_cart_session_${this.storeContextId()}`;
 		return [...this.cookies.keys()].some((name) => name === prefix || name.startsWith(`${prefix}_`));
 	}
@@ -135,13 +186,24 @@ var CaldikHttpClient = class {
 			const error = await response.clone().json().catch(() => null);
 			throw new CaldikHttpError(typeof error?.message === "string" && error.message ? error.message : `${response.status} ${response.statusText}`.trim(), response.status);
 		}
+		if (options?.empty) return void 0;
 		return response.json();
 	}
 	get(path, params, options) {
-		return this.request("GET", path, void 0, params, options);
+		return new CaldikRequest(this, {
+			method: "GET",
+			path,
+			params,
+			empty: options?.empty
+		}, () => this.request("GET", path, void 0, params, options));
 	}
 	post(path, input, options) {
-		return this.request("POST", path, input, void 0, options);
+		return new CaldikRequest(this, {
+			method: "POST",
+			path,
+			input,
+			empty: options?.empty
+		}, () => this.request("POST", path, input, void 0, options));
 	}
 };
 //#endregion
@@ -224,8 +286,15 @@ var CustomerApi = class {
 	login;
 	register;
 	password;
+	orders;
+	balance;
 	constructor(client) {
 		this.client = client;
+		this.orders = {
+			list: (options = {}) => client.get("/customers/orders", { ...options }, { access: "public" }),
+			get: (id) => client.get(`/customers/orders/${encodeURIComponent(id)}`, void 0, { access: "public" })
+		};
+		this.balance = { get: (options = {}) => client.get("/customers/balance", { ...options }, { access: "public" }) };
 		this.settings = { get: () => this.client.get("/customers/settings", void 0, { access: "public" }) };
 		let pendingResetId;
 		this.password = {
@@ -293,11 +362,14 @@ verify: async (code, challengeId = pendingRegistrationId) => {
 			return response;
 		} });
 	}
-	/** Check a store-scoped session without raising an error for signed-out customers. */
+	/** Resolves without a body on HTTP 200; rejects with status 401 when signed out. */
 	session() {
-		return this.client.get("/customers/session", void 0, { access: "public" });
+		return this.client.get("/customers/session", void 0, {
+			access: "public",
+			empty: true
+		});
 	}
-	/** Read the signed-in customer and their balances. */
+	/** Read the signed-in customer's profile. */
 	me() {
 		return this.client.get("/customers/me", void 0, { access: "public" });
 	}
@@ -378,7 +450,6 @@ function discountFromQuote(quote) {
 var CartApi = class {
 	client;
 	cache = {
-		version: 2,
 		reference: null,
 		snapshot: {
 			items: [],
@@ -411,18 +482,16 @@ var CartApi = class {
 		if (!storage) return;
 		try {
 			const parsed = JSON.parse(storage.getItem(this.key()) || "null");
-			if (parsed?.version === 2) {
+			if (parsed?.snapshot) {
 				const snapshot = parsed.snapshot;
 				if (snapshot && Array.isArray(snapshot.items) && snapshot.items.every(isCartItem) && (parsed.reference === null || isReference(parsed.reference))) this.cache = {
-					version: 2,
 					reference: parsed.reference,
 					snapshot: cloneSnapshot({
 						items: snapshot.items,
 						discount: isCartDiscount(snapshot.discount) ? snapshot.discount : null
 					})
 				};
-			} else if (parsed?.version === 1 && Array.isArray(parsed.items) && parsed.items.every(isCartItem)) this.cache = {
-				version: 2,
+			} else if (parsed && Array.isArray(parsed.items) && parsed.items.every(isCartItem)) this.cache = {
 				reference: null,
 				snapshot: cloneSnapshot({
 					items: parsed.items,
@@ -444,7 +513,6 @@ var CartApi = class {
 	}
 	write(cart, token = this.cache.reference?.token, discount = null) {
 		this.cache = {
-			version: 2,
 			reference: {
 				id: cart.id,
 				token: cart.customerId ? null : token
@@ -492,7 +560,6 @@ var CartApi = class {
 	}
 	reset() {
 		this.cache = {
-			version: 2,
 			reference: null,
 			snapshot: {
 				items: [],
@@ -502,25 +569,11 @@ var CartApi = class {
 		this.persistCache();
 	}
 	async mutate(operation, seed = true) {
-		let cart = await this.resolve(false, seed);
-		let response;
-		try {
-			response = await operation(cart);
-		} catch (error) {
-			if (!(error instanceof CaldikHttpError) || error.status !== 409) throw error;
-			const refreshed = await this.resolve();
-			if (refreshed.id !== cart.id || refreshed.status !== "active") throw error;
-			cart = refreshed;
-			response = await operation(cart);
-		}
+		const response = await operation(await this.resolve(false, seed));
 		return this.write(response.cart);
 	}
-	save(cart, items, discountCode) {
-		return this.client.post(`/carts/${cart.id}`, {
-			items: commerceItems(items),
-			version: cart.version,
-			discountCode
-		}, this.options());
+	saveDiscount(cart, code) {
+		return this.client.post(`/carts/${cart.id}/discount`, { code }, this.options());
 	}
 	quote(cart, code) {
 		if (!cart.items.length) throw new Error("Cannot check a discount on an empty cart");
@@ -541,7 +594,7 @@ var CartApi = class {
 					404,
 					422
 				].includes(error.status)) throw error;
-				cart = (await this.save(cart, cart.items, null)).cart;
+				cart = (await this.saveDiscount(cart, null)).cart;
 			}
 			return this.write(cart, this.cache.reference?.token, discount);
 		});
@@ -554,10 +607,7 @@ var CartApi = class {
 				productId: item.productId.trim(),
 				quantity: quantity(item.quantity)
 			};
-			return this.mutate((cart) => this.client.post(`/carts/${cart.id}/items`, {
-				item: normalized,
-				version: cart.version
-			}, this.options()));
+			return this.mutate((cart) => this.client.post(`/carts/${cart.id}/items`, { item: normalized }, this.options()));
 		});
 	}
 	updateQuantity(itemId, nextQuantity) {
@@ -565,11 +615,10 @@ var CartApi = class {
 			const normalized = quantity(nextQuantity, true);
 			return this.mutate((cart) => {
 				if (!cart.items.some((item) => item.id === itemId)) throw new Error("Cart item not found");
-				const items = cart.items.map((item) => item.id === itemId ? {
-					...item,
+				return this.client.post(`/carts/${cart.id}/items/quantity`, {
+					itemId,
 					quantity: normalized
-				} : item).filter((item) => item.quantity > 0);
-				return this.save(cart, items, null);
+				}, this.options());
 			});
 		});
 	}
@@ -577,7 +626,7 @@ var CartApi = class {
 		return this.updateQuantity(itemId, 0);
 	}
 	clear() {
-		return this.enqueue(() => this.mutate((cart) => this.save(cart, [], null), false));
+		return this.enqueue(() => this.mutate((cart) => this.client.post(`/carts/${cart.id}/clear`, {}, this.options()), false));
 	}
 	checkDiscount(code) {
 		return this.enqueue(async () => this.quote(await this.resolve(), code));
@@ -587,7 +636,9 @@ var CartApi = class {
 			let quote;
 			const snapshot = await this.mutate(async (cart) => {
 				quote = await this.quote(cart, code);
-				return this.save(cart, cart.items, quote.discount.code);
+				const response = await this.saveDiscount(cart, quote.discount.code);
+				quote = await this.quote(response.cart, quote.discount.code);
+				return response;
 			});
 			snapshot.discount = discountFromQuote(quote);
 			this.cache.snapshot = cloneSnapshot(snapshot);
@@ -596,22 +647,92 @@ var CartApi = class {
 		});
 	}
 	removeDiscount() {
-		return this.enqueue(() => this.mutate((cart) => this.save(cart, cart.items, null)));
+		return this.enqueue(() => this.mutate((cart) => this.saveDiscount(cart, null)));
 	}
 	checkout(input = {}) {
 		return this.enqueue(async () => {
 			const cart = await this.resolve(true);
 			if (!cart.items.length) throw new Error("Cannot checkout an empty cart");
-			const response = await this.client.post(`/carts/${cart.id}/checkout`, {
-				...input,
-				version: cart.version
-			}, this.options());
+			const response = await this.client.post(`/carts/${cart.id}/checkout`, input, this.options());
 			this.reset();
 			return response;
 		});
 	}
 };
 //#endregion
+//#region src/batch.ts
+var CaldikBatchError = class extends Error {
+	results;
+	errors;
+	constructor(results, errors) {
+		super(`Batch requests failed: ${Object.keys(errors).join(", ")}`);
+		this.results = results;
+		this.errors = errors;
+		this.name = "CaldikBatchError";
+	}
+};
+function batchRequests(client, input) {
+	const entries = Object.entries(input);
+	const seen = /* @__PURE__ */ new Set();
+	try {
+		if (!entries.length || entries.length > 25) throw new Error("A batch must contain between 1 and 25 requests");
+		for (const [key, request] of entries) {
+			if (!/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(key) || ["constructor", "prototype"].includes(key)) throw new Error("Invalid batch key");
+			if (!(request instanceof CaldikRequest) || request.owner !== client || request.started || seen.has(request)) throw new Error("Batch values must be unstarted, distinct requests from the same Caldik client");
+			if (request.descriptor.method !== "GET" && !/^\/plugins\/sdk\/[^/]+\/[^/]+$/.test(request.descriptor.path)) throw new Error("Batches support read requests only");
+			seen.add(request);
+		}
+	} catch (error) {
+		for (const [, request] of entries) if (request instanceof CaldikRequest) request.cancel(error);
+		throw error;
+	}
+	const response = client.post("/batch", { requests: Object.fromEntries(entries.map(([key, request]) => [key, {
+		method: request.descriptor.method,
+		path: request.descriptor.path,
+		query: request.descriptor.params,
+		input: request.descriptor.input
+	}])) }, { access: "public" }).then((value) => value.results);
+	for (const [key, request] of entries) request.bind(response.then((results) => {
+		const result = results[key];
+		if (!result) throw new Error(`Missing batch result: ${key}`);
+		if (result.status < 200 || result.status >= 300) {
+			const body = result.body;
+			throw new CaldikHttpError(body?.message || `HTTP ${result.status}`, result.status);
+		}
+		return request.descriptor.empty ? void 0 : result.body;
+	}));
+	return response.then((results) => {
+		const values = {};
+		const errors = {};
+		for (const [key, request] of entries) {
+			const result = results[key];
+			if (!result) throw new Error(`Missing batch result: ${key}`);
+			if (result.status >= 200 && result.status < 300) values[key] = request.descriptor.empty ? void 0 : result.body;
+			else errors[key] = result;
+		}
+		if (Object.keys(errors).length) throw new CaldikBatchError(values, errors);
+		return values;
+	});
+}
+//#endregion
+//#region src/plugins.ts
+function createPluginApi(client) {
+	const namespaces = /* @__PURE__ */ new Map();
+	const safe = (value) => /^[a-zA-Z][a-zA-Z0-9_\-]{0,63}$/.test(value) && ![
+		"constructor",
+		"prototype",
+		"then"
+	].includes(value);
+	return new Proxy(Object.create(null), { get(_target, namespace) {
+		if (typeof namespace !== "string" || !safe(namespace)) return void 0;
+		if (!namespaces.has(namespace)) namespaces.set(namespace, new Proxy(Object.create(null), { get(_target, method) {
+			if (typeof method !== "string" || !safe(method)) return void 0;
+			return (input = {}) => client.post(`/plugins/sdk/${encodeURIComponent(namespace)}/${encodeURIComponent(method)}`, input, { access: "public" });
+		} }));
+		return namespaces.get(namespace);
+	} });
+}
+//#endregion
 //#region src/payment-providers.generated.ts
 const paymentProviderIds = [
 	"customer_balance",
@@ -662,9 +783,13 @@ var CaldikClient = class {
 	store;
 	checkout;
 	customer;
+	customers;
+	orders;
+	plugins;
 	subscriptions;
 	discounts;
 	cart;
+	client;
 	constructor(options = {}) {
 		const client = new CaldikHttpClient({
 			apiKey: options.apiKey,
@@ -673,16 +798,23 @@ var CaldikClient = class {
 			request: options.request,
 			onSetCookie: options.onSetCookie
 		});
+		this.client = client;
 		this.categories = new CategoriesApi(client);
 		this.products = new ProductsApi(client);
 		this.reviews = new ReviewsApi(client);
 		this.store = new StoreApi(client);
 		this.checkout = new CheckoutApi(client);
 		this.customer = new CustomerApi(client);
+		this.customers = this.customer;
+		this.orders = this.customer.orders;
+		this.plugins = createPluginApi(client);
 		this.subscriptions = new SubscriptionsApi(client);
 		this.discounts = new DiscountsApi(client);
 		this.cart = new CartApi(client);
 	}
+	batch(input) {
+		return batchRequests(this.client, input);
+	}
 };
 //#endregion
-export { CaldikClient, CartApi, DiscountsApi, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };
+export { CaldikBatchError, CaldikClient, CaldikHttpError, CaldikRequest, CartApi, DiscountsApi, batchRequests, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caldik/client",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -8,16 +8,22 @@
     ".": {
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
+    },
+    "./development": {
+      "types": "./dist/development.d.mts",
+      "default": "./dist/development.mjs"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "types"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && node development/prepare-types.mjs",
+    "prepack": "node development/prepare-types.mjs",
     "sync:api-contracts": "bun scripts/sync-api-contracts.ts",
     "test": "bun test"
   },

package/types/plugins.d.ts

@@ -0,0 +1,7 @@
+// Generated by Caldik. Plugin contracts refresh automatically during caldik dev.
+import type { CaldikRequest } from "@caldik/client";
+
+declare module "@caldik/client" {
+  interface CaldikPlugins {
+  }
+}