@caldik/client 0.1.7 → 0.1.9

package/README.md

@@ -165,7 +165,7 @@ 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
+The SDK manages the `cart_{storeId}` 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.
 
@@ -389,8 +389,14 @@ await caldik.customer.session()
 ```ts
 const { customer } = await caldik.customers.me()
 console.log(customer.name, customer.email)
+console.log(customer.totalOrders, customer.totalSpent, customer.currency)
 ```
 
+`totalOrders` counts this customer's orders in the store. `totalSpent` is a
+decimal string summing successful payments after discounts in the store's
+currency; unpaid, failed, refunded and other-currency orders are excluded from
+spending. This profile does not include `shortId` or `displayId`.
+
 **List the customer's orders**
 
 ```ts
@@ -533,6 +539,7 @@ await caldik.customer.register.verify(code)
 
 > **Note:** The `username` field is provided by the Customer Usernames plugin. Omit this field when the plugin is not installed.
 
+
 ## Payment Methods and Settings
 
 Retrieve customer authentication settings, checkout configuration, and available payment methods.

package/dist/development.mjs

@@ -17,6 +17,7 @@ const safeKey = (value) => typeof value === "string" && /^[a-zA-Z][a-zA-Z0-9_\-]
 	"prototype",
 	"then"
 ].includes(value);
+const reservedParameters = new Set("await break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public".split(" "));
 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) {
@@ -46,8 +47,8 @@ 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\";",
+		"// Generated by Caldik.",
+		`import type { CaldikRequest${metadata.plugins.some((plugin) => plugin?.methods && typeof plugin.methods === "object" && Object.values(plugin.methods).some((method) => method?.subscription)) ? ", CaldikSubscriptionOptions" : ""} } from "@caldik/client";`,
 		"",
 		"declare module \"@caldik/client\" {",
 		"  interface CaldikPlugins {"
@@ -56,14 +57,64 @@ function generatePluginTypes(metadata) {
 		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)}: {`);
+		const tree = Object.create(null);
 		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}>;`);
+			const keys = name.split(".");
+			if (keys.length > 4 || !keys.every(safeKey) || !method || typeof method !== "object") throw new Error("Invalid plugin method");
+			let branch = tree;
+			for (const key of keys.slice(0, -1)) {
+				branch[key] ??= { children: Object.create(null) };
+				if (!branch[key].children) throw new Error("Conflicting plugin method group");
+				branch = branch[key].children;
+			}
+			if (branch[keys.at(-1)]) throw new Error("Conflicting plugin method group");
+			branch[keys.at(-1)] = { method };
 		}
+		const render = (branch, indent) => {
+			for (const [name, entry] of Object.entries(branch)) {
+				if (entry.children) {
+					lines.push(`${indent}readonly ${JSON.stringify(name)}: {`);
+					render(entry.children, indent + "  ");
+					lines.push(`${indent}};`);
+					continue;
+				}
+				const method = entry.method, input = schemaType(method.input), output = schemaType(method.output);
+				let parameters;
+				if (method.parameters !== void 0) {
+					const properties = method.input.properties ?? {}, required = method.input.required ?? [];
+					if (!Array.isArray(method.parameters) || !method.parameters.length || method.parameters.length > 4 || new Set(method.parameters).size !== method.parameters.length || method.input.type !== "object" || method.parameters.some((key) => !safeKey(key) || !Object.hasOwn(properties, key)) || Object.keys(properties).some((key) => !method.parameters.includes(key))) throw new Error("Invalid plugin parameters");
+					let optional = false;
+					parameters = method.parameters.map((key, index) => {
+						const needed = required.includes(key);
+						if (needed && optional) throw new Error("Required parameter follows optional parameter");
+						optional ||= !needed;
+						let identifier = key;
+						if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(key) || reservedParameters.has(key)) {
+							identifier = `argument_${index + 1}`;
+							while (method.parameters.includes(identifier)) identifier += "_";
+						}
+						return `${identifier}${needed ? "" : "?"}: ${schemaType(properties[key])}`;
+					}).join(", ");
+				} else {
+					const empty = method.input.type === "object" && !Object.keys(method.input.properties ?? {}).length;
+					const optional = method.input.type === "object" && !method.input.required?.length;
+					parameters = empty ? "" : `input${optional ? "?" : ""}: ${input}`;
+				}
+				if (method.subscription) {
+					const events = method.subscription.events;
+					if (!method.parameters || method.parameters.some((key) => !method.input.required?.includes(key)) || !events || typeof events !== "object" || Array.isArray(events) || !Object.keys(events).length || Object.keys(events).length > 8 || Object.keys(events).some((key) => !safeKey(key) || [
+						"onError",
+						"ready",
+						"error"
+					].includes(key))) throw new Error("Invalid plugin subscription");
+					const type = `{ ${Object.entries(events).map(([key, schema]) => `${JSON.stringify(key)}: ${schemaType(schema)};`).join(" ")} }`;
+					let optionName = "callbacks";
+					while (method.parameters.includes(optionName)) optionName += "_";
+					lines.push(`${indent}readonly ${JSON.stringify(name)}: (${parameters}${parameters ? ", " : ""}${optionName}: CaldikSubscriptionOptions<${type}>) => () => void;`);
+				} else lines.push(`${indent}readonly ${JSON.stringify(name)}: (${parameters}) => CaldikRequest<${output}>;`);
+			}
+		};
+		render(tree, "      ");
 		lines.push("    };");
 	}
 	lines.push("  }", "}", "");

package/dist/index.d.mts

@@ -204,7 +204,7 @@ interface StorefrontOrder {
     code: string | null;
     percentage: string;
     amount: string;
-    source: "code" | "loyalty";
+    source: "code" | "plugin";
   } | null;
   currency: string;
 }
@@ -324,11 +324,12 @@ interface CustomerProfileResponse {
   success: boolean;
   customer: {
     id: string;
-    shortId: string;
-    displayId: string;
     name: string | null;
     email: string | null;
-    phone: string | null;
+    phone: string | null; /** All orders belonging to this customer in this store. */
+    totalOrders: number; /** Successfully paid order amounts in the store currency, as a decimal string. */
+    totalSpent: string;
+    currency: string;
     createdAt: number;
     updatedAt: number;
     extensions: Record<string, Record<string, string | number | boolean>>;
@@ -360,7 +361,7 @@ interface CustomerOrder {
     code: string | null;
     percentage: string;
     amount: string;
-    source: "code" | "loyalty";
+    source: "code" | "plugin";
   } | null;
 }
 interface CustomerOrderItem {
@@ -484,7 +485,9 @@ declare class CaldikHttpClient {
   customerAuthenticated(): Promise<void>;
   private captureCookies;
   private baseUrl;
+  private response;
   private request;
+  stream(path: string, input: unknown, signal: AbortSignal, cursor?: string): Promise<Response>;
   get<T>(path: string, params?: Record<string, string | number>, options?: RequestOptions): CaldikRequest<T>;
   post<T>(path: string, input?: unknown, options?: RequestOptions): CaldikRequest<T>;
 }
@@ -668,6 +671,11 @@ declare class CartApi {
   checkout(input?: CartCheckoutInput): Promise<OrderResponse>;
 }
 //#endregion
+//#region src/internal/realtime.d.ts
+type CaldikSubscriptionOptions<T extends Record<string, unknown>> = { [K in keyof T]?: (value: T[K]) => void } & {
+  onError?: (error: Error) => void;
+};
+//#endregion
 //#region src/index.d.ts
 /** Populated automatically from the store's plugin contracts during caldik dev. */
 interface CaldikPlugins {}
@@ -703,4 +711,4 @@ declare class CaldikClient {
   batch<T extends BatchInput>(input: T): Promise<BatchResult<T>>;
 }
 //#endregion
-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 };
+export { AppliedDiscount, BatchInput, BatchResult, CaldikBatchError, CaldikClient, CaldikClientOptions, CaldikHttpError, CaldikPlugins, CaldikRequest, type CaldikSubscriptionOptions, 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

@@ -124,7 +124,7 @@ var CaldikHttpClient = class {
 		return this.storeId || boundRuntimeStoreId();
 	}
 	hasCartSession() {
-		if (this.cookies.has("session")) return true;
+		if (this.cookies.has(`cart_${this.storeContextId()}`) || this.cookies.has("session")) return true;
 		const prefix = `caldik_cart_session_${this.storeContextId()}`;
 		return [...this.cookies.keys()].some((name) => name === prefix || name.startsWith(`${prefix}_`));
 	}
@@ -163,7 +163,7 @@ var CaldikHttpClient = class {
 		if (!boundStoreId && !this.apiKey) throw new Error("Caldik authentication is unavailable. External servers must provide a private apiKey.");
 		return `${this.apiUrl.replace(/\/+$/, "")}/v1/stores/${encodeURIComponent(storeId)}`;
 	}
-	async request(method, path, input, params, options) {
+	async response(method, path, input, params, options, signal) {
 		const url = new URL(`${this.baseUrl()}${path}`);
 		if (params) for (const [key, value] of Object.entries(params)) url.searchParams.set(key, String(value));
 		const headers = { ...options?.headers };
@@ -179,16 +179,30 @@ var CaldikHttpClient = class {
 			headers,
 			...input !== void 0 ? { body: JSON.stringify(input) } : {},
 			cache: "default",
-			credentials: "include"
+			credentials: "include",
+			signal
 		});
 		if (!isBrowserRuntime() && options?.access === "public") await this.captureCookies(response);
 		if (!response.ok) {
 			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);
 		}
+		return response;
+	}
+	async request(method, path, input, params, options) {
+		const response = await this.response(method, path, input, params, options);
 		if (options?.empty) return void 0;
 		return response.json();
 	}
+	stream(path, input, signal, cursor) {
+		return this.response("POST", path, input, void 0, {
+			access: "public",
+			headers: {
+				Accept: "text/event-stream",
+				...cursor ? { "Last-Event-ID": cursor } : {}
+			}
+		}, signal);
+	}
 	get(path, params, options) {
 		return new CaldikRequest(this, {
 			method: "GET",
@@ -679,7 +693,7 @@ function batchRequests(client, input) {
 		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");
+			if (request.descriptor.method !== "GET" && !/^\/plugins\/sdk\/[a-zA-Z][a-zA-Z0-9_-]*\/[a-zA-Z][a-zA-Z0-9_-]*(?:\/[a-zA-Z][a-zA-Z0-9_-]*){0,3}$/.test(request.descriptor.path)) throw new Error("Batches support read requests only");
 			seen.add(request);
 		}
 	} catch (error) {
@@ -715,6 +729,91 @@ function batchRequests(client, input) {
 	});
 }
 //#endregion
+//#region src/internal/realtime.ts
+/** Native SSE transport. */
+function subscribePlugin(client, path, args, callbacks) {
+	const controller = new AbortController();
+	let cursor;
+	let timer;
+	let retries = 0;
+	const report = (error) => {
+		try {
+			if (typeof callbacks.onError === "function") callbacks.onError(error instanceof Error ? error : /* @__PURE__ */ new Error("Realtime connection failed"));
+		} catch {}
+	};
+	const frame = (value) => {
+		let event = "message", data = "", id;
+		for (const line of value.split("\n")) if (line.startsWith("event:")) event = line.slice(6).trim();
+		else if (line.startsWith("data:")) data += (data ? "\n" : "") + line.slice(5).trimStart();
+		else if (line.startsWith("id:")) id = line.slice(3).trim();
+		if (event === "error") throw new CaldikHttpError("Subscription authorization changed", 403);
+		if (id && /^\d{1,20}$/.test(id)) cursor = id;
+		if (["ready", "heartbeat"].includes(event) || !data) return;
+		const callback = Object.hasOwn(callbacks, event) ? callbacks[event] : void 0;
+		if (typeof callback === "function") {
+			let parsed;
+			try {
+				parsed = JSON.parse(data);
+			} catch {
+				throw new Error("Invalid realtime event");
+			}
+			try {
+				callback(parsed);
+			} catch (error) {
+				report(error);
+			}
+		}
+	};
+	const connect = async () => {
+		let reader;
+		try {
+			const response = await client.stream(path, args, controller.signal, cursor);
+			if (!response.headers.get("Content-Type")?.startsWith("text/event-stream") || !response.body) throw new Error("Invalid realtime response");
+			reader = response.body.getReader();
+			retries = 0;
+			const decoder = new TextDecoder();
+			let buffer = "";
+			while (!controller.signal.aborted) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				buffer += decoder.decode(value, { stream: true });
+				buffer = buffer.replaceAll("\r\n", "\n");
+				let end;
+				while ((end = buffer.indexOf("\n\n")) !== -1) {
+					const next = buffer.slice(0, end);
+					buffer = buffer.slice(end + 2);
+					if (next.length > 65536) throw new Error("Realtime event exceeds its size limit");
+					frame(next);
+				}
+				if (buffer.length > 65536) throw new Error("Realtime event exceeds its size limit");
+			}
+		} catch (error) {
+			if (controller.signal.aborted) return;
+			report(error);
+			if (error instanceof CaldikHttpError && [
+				400,
+				401,
+				403,
+				404,
+				405
+			].includes(error.status)) {
+				controller.abort();
+				return;
+			}
+		} finally {
+			await reader?.cancel().catch(() => void 0);
+		}
+		if (!controller.signal.aborted) timer = setTimeout(() => {
+			connect();
+		}, Math.min(1e4, 500 * 2 ** Math.min(retries++, 5)));
+	};
+	connect();
+	return () => {
+		controller.abort();
+		if (timer) clearTimeout(timer);
+	};
+}
+//#endregion
 //#region src/plugins.ts
 function createPluginApi(client) {
 	const namespaces = /* @__PURE__ */ new Map();
@@ -725,9 +824,25 @@ function createPluginApi(client) {
 	].includes(value);
 	return new Proxy(Object.create(null), { get(_target, namespace) {
 		if (typeof namespace !== "string" || !safe(namespace)) return void 0;
+		const methodProxy = (keys) => new Proxy(() => void 0, {
+			get(_target, key) {
+				if (typeof key !== "string" || !safe(key) || keys.length >= 4) return void 0;
+				return methodProxy([...keys, key]);
+			},
+			apply(_target, _this, args) {
+				while (args.length && args.at(-1) === void 0) args.pop();
+				const path = `/plugins/sdk/${encodeURIComponent(namespace)}/${keys.map(encodeURIComponent).join("/")}`;
+				if (keys.at(-1) === "subscribe") {
+					const callbacks = args.at(-1);
+					if (!callbacks || typeof callbacks !== "object" || Array.isArray(callbacks)) throw new Error("Provide subscription callbacks");
+					return subscribePlugin(client, path, args.slice(0, -1), callbacks);
+				}
+				return client.post(path, keys.length > 1 ? args : args[0] ?? {}, { access: "public" });
+			}
+		});
 		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 methodProxy([method]);
 		} }));
 		return namespaces.get(namespace);
 	} });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caldik/client",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",

package/types/plugins.d.ts

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