@caldik/client 0.0.4 → 0.0.6

package/README.md

@@ -22,3 +22,9 @@ const caldik = new CaldikClient({
   apiKey: process.env.CALDIK_PRIVATE_API_KEY,
 })
 ```
+
+## Canonical contracts
+
+```ts
+const { events, catalogVersion } = await caldik.webhooks.events()
+```

package/dist/index.d.mts

@@ -1,4 +1,24 @@
+//#region src/payment-providers.generated.d.ts
+declare const paymentProviderIds: readonly ["customer_balance", "stripe", "ovgc"];
+declare const checkoutPaymentProviderIds: readonly ["customer_balance", "stripe", "ovgc"];
+declare const subscriptionPaymentProviderIds: readonly ["stripe"];
+type PaymentProviderId = typeof paymentProviderIds[number];
+type CheckoutPaymentProviderId = typeof checkoutPaymentProviderIds[number];
+type SubscriptionPaymentProviderId = typeof subscriptionPaymentProviderIds[number];
+//#endregion
+//#region src/store-events.generated.d.ts
+declare const storeWebhookEventNames: readonly ["store.updated", "store.suspended", "store.restored", "domain.created", "domain.updated", "domain.deleted", "member.invited", "member.updated", "member.removed", "member.invite_revoked", "product.created", "product.updated", "product.deleted", "category.created", "category.updated", "category.deleted", "discount.created", "discount.updated", "discount.deleted", "customer.created", "customer.updated", "order.created", "order.updated", "subscription.created", "subscription.updated"];
+type StoreWebhookEventName = typeof storeWebhookEventNames[number];
+//#endregion
 //#region src/types.d.ts
+interface StorefrontMetadata {
+  id: string;
+  title: string;
+  description: string;
+  json: Record<string, unknown>;
+}
+type ProductMetadata = StorefrontMetadata;
+type CategoryMetadata = StorefrontMetadata;
 interface Category {
   id: string;
   name: string;
@@ -7,6 +27,7 @@ interface Category {
   price: string;
   logo: string | null;
   banner: string | null;
+  metadata: CategoryMetadata[];
 }
 interface CategoriesResponse {
   success: boolean;
@@ -27,7 +48,11 @@ interface CategoryProduct {
 interface CategoryDetails {
   id: string;
   name: string;
+  slug: string;
   description: string;
+  logo: string | null;
+  banner: string | null;
+  metadata: CategoryMetadata[];
   products: CategoryProduct[];
 }
 interface CategoryResponse {
@@ -68,6 +93,8 @@ interface Product {
   maximumQuantity: number | null;
   variants: ProductVariant[];
   tags: ProductTag[];
+  customFields: ProductCustomField[];
+  metadata: ProductMetadata[];
 }
 interface ProductVariant {
   id: string;
@@ -79,6 +106,23 @@ interface ProductTag {
   label: string;
   color: string;
 }
+type ProductCustomFieldInputType = "text" | "textarea" | "number" | "dropdown" | "checkbox";
+interface ProductCustomFieldOption {
+  id: string;
+  label: string;
+  value: string;
+  position: number;
+}
+interface ProductCustomField {
+  id: string;
+  name: string;
+  inputType: ProductCustomFieldInputType;
+  placeholder: string | null;
+  position: number;
+  defaultValue: string | null;
+  requiredEnabled: boolean;
+  options: ProductCustomFieldOption[];
+}
 interface ProductsResponse {
   success: boolean;
   products: Product[];
@@ -102,7 +146,7 @@ type CommerceItem = ManualCommerceItem | ProductCommerceItem;
 interface CreateOrderInput {
   customerId?: string;
   email?: string;
-  paymentMethod: "customer_balance" | "stripe" | "ovgc";
+  paymentMethod: CheckoutPaymentProviderId;
   items: CommerceItem[];
   successUrl?: string;
   cancelUrl?: string;
@@ -118,7 +162,7 @@ interface StorefrontOrder {
   currency: string;
 }
 interface CheckoutPayment {
-  type: "customer_balance" | "stripe" | "ovgc";
+  type: CheckoutPaymentProviderId;
   checkoutUrl?: string | null;
   checkoutSessionId?: string | null;
   balanceAfter?: string;
@@ -131,6 +175,7 @@ interface OrderResponse {
 interface CreateSubscriptionInput {
   customerId?: string;
   email?: string;
+  paymentMethod?: SubscriptionPaymentProviderId;
   items: CommerceItem[];
   billingInterval: "day" | "week" | "month" | "year";
   billingIntervalCount?: number;
@@ -152,11 +197,33 @@ interface SubscriptionResponse {
     currency: string;
   };
   payment: {
-    type: "stripe";
+    type: SubscriptionPaymentProviderId;
     checkoutUrl: string;
     checkoutSessionId: string;
   };
 }
+interface StoreWebhookEventDefinition {
+  name: StoreWebhookEventName;
+  resource: string;
+  action: string;
+  description: string;
+}
+interface StoreWebhookEventsResponse {
+  success: boolean;
+  apiVersion: "v1";
+  catalogVersion: string;
+  events: StoreWebhookEventDefinition[];
+}
+interface StoreWebhookEvent<TObject extends Record<string, unknown> = Record<string, unknown>> {
+  id: string;
+  type: StoreWebhookEventName;
+  createdAt: number;
+  storeId: string;
+  data: {
+    object: TObject;
+    previousAttributes?: Record<string, unknown>;
+  };
+}
 interface CustomerLoginResponse {
   success: boolean;
   message: string;
@@ -249,6 +316,14 @@ declare class SubscriptionsApi {
   create(input: CreateSubscriptionInput): Promise<SubscriptionResponse>;
 }
 //#endregion
+//#region src/webhooks.d.ts
+declare class WebhooksApi {
+  private client;
+  constructor(client: CaldikHttpClient);
+  /** Lists the canonical events accepted by store webhook subscriptions. */
+  events(): Promise<StoreWebhookEventsResponse>;
+}
+//#endregion
 //#region src/index.d.ts
 interface CaldikClientOptions {
   /** Store ID for external servers. Hosted Workers receive it automatically. */
@@ -265,7 +340,8 @@ declare class CaldikClient {
   readonly checkout: CheckoutApi;
   readonly customer: CustomerApi;
   readonly subscriptions: SubscriptionsApi;
+  readonly webhooks: WebhooksApi;
   constructor(options?: CaldikClientOptions);
 }
 //#endregion
-export { CaldikClient, CaldikClientOptions, CategoriesResponse, Category, CategoryDetails, CategoryProduct, CategoryResponse, CheckoutPayment, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerLoginResponse, CustomerLoginVerifyResponse, ManualCommerceItem, OrderResponse, Product, ProductCommerceItem, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StorefrontOrder, SubscriptionResponse };
+export { CaldikClient, CaldikClientOptions, CategoriesResponse, Category, CategoryDetails, CategoryMetadata, CategoryProduct, CategoryResponse, CheckoutPayment, CheckoutPaymentProviderId, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerLoginResponse, CustomerLoginVerifyResponse, ManualCommerceItem, OrderResponse, PaymentProviderId, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreWebhookEvent, StoreWebhookEventDefinition, StoreWebhookEventName, StoreWebhookEventsResponse, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };

package/dist/index.mjs

@@ -10,6 +10,21 @@ function boundRuntimeStoreId() {
 	const storeId = globalThis.process?.env?.CALDIK_STORE_ID?.trim();
 	return storeId && STORE_ID_PATTERN.test(storeId) ? storeId : null;
 }
+function browserRuntimeStoreId() {
+	const cookies = typeof document.cookie === "string" ? document.cookie : "";
+	for (const item of cookies.split(";")) {
+		const separator = item.indexOf("=");
+		if (separator < 1) continue;
+		if (item.slice(0, separator).trim() !== "__Host-caldik-store-id") continue;
+		try {
+			const value = decodeURIComponent(item.slice(separator + 1).trim());
+			return STORE_ID_PATTERN.test(value) ? value : null;
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
 var CaldikHttpClient = class {
 	apiKey;
 	apiUrl;
@@ -24,8 +39,9 @@ var CaldikHttpClient = class {
 	}
 	baseUrl() {
 		if (isBrowserRuntime()) {
-			if (typeof location === "undefined") throw new Error("Caldik browser transport requires a browser origin");
-			return new URL("/__caldik/api", location.origin).toString().replace(/\/+$/, "");
+			const storeId = this.storeId || browserRuntimeStoreId();
+			if (!storeId) throw new Error("Caldik storefront context is unavailable. Hosted storefronts receive it automatically; local or externally hosted browsers must provide storeId.");
+			return `${this.apiUrl.replace(/\/+$/, "")}/v1/stores/${encodeURIComponent(storeId)}`;
 		}
 		const boundStoreId = boundRuntimeStoreId();
 		if (boundStoreId && this.storeId && boundStoreId !== this.storeId) throw new Error("Caldik storeId does not match the hosted runtime");
@@ -40,7 +56,7 @@ var CaldikHttpClient = class {
 		const headers = {};
 		if (!isBrowserRuntime()) headers["User-Agent"] = "CaldikClient/0.0.2";
 		if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
-		else if (options?.access === "public") headers["X-Caldik-Public-Request"] = "1";
+		else if (options?.access === "public" && !isBrowserRuntime()) headers["X-Caldik-Public-Request"] = "1";
 		if (input !== void 0) headers["Content-Type"] = "application/json";
 		if (options?.edgeCache) headers["X-Cache-Policy"] = "public";
 		const response = await fetch(url, {
@@ -154,6 +170,60 @@ var SubscriptionsApi = class {
 	}
 };
 //#endregion
+//#region src/webhooks.ts
+var WebhooksApi = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/** Lists the canonical events accepted by store webhook subscriptions. */
+	events() {
+		return this.client.get("/webhooks/events");
+	}
+};
+//#endregion
+//#region src/payment-providers.generated.ts
+const paymentProviderIds = [
+	"customer_balance",
+	"stripe",
+	"ovgc"
+];
+const checkoutPaymentProviderIds = [
+	"customer_balance",
+	"stripe",
+	"ovgc"
+];
+const subscriptionPaymentProviderIds = ["stripe"];
+//#endregion
+//#region src/store-events.generated.ts
+const storeWebhookEventNames = [
+	"store.updated",
+	"store.suspended",
+	"store.restored",
+	"domain.created",
+	"domain.updated",
+	"domain.deleted",
+	"member.invited",
+	"member.updated",
+	"member.removed",
+	"member.invite_revoked",
+	"product.created",
+	"product.updated",
+	"product.deleted",
+	"category.created",
+	"category.updated",
+	"category.deleted",
+	"discount.created",
+	"discount.updated",
+	"discount.deleted",
+	"customer.created",
+	"customer.updated",
+	"order.created",
+	"order.updated",
+	"subscription.created",
+	"subscription.updated"
+];
+//#endregion
 //#region src/index.ts
 var CaldikClient = class {
 	categories;
@@ -163,6 +233,7 @@ var CaldikClient = class {
 	checkout;
 	customer;
 	subscriptions;
+	webhooks;
 	constructor(options = {}) {
 		const client = new CaldikHttpClient({
 			apiKey: options.apiKey,
@@ -176,7 +247,8 @@ var CaldikClient = class {
 		this.checkout = new CheckoutApi(client);
 		this.customer = new CustomerApi(client);
 		this.subscriptions = new SubscriptionsApi(client);
+		this.webhooks = new WebhooksApi(client);
 	}
 };
 //#endregion
-export { CaldikClient };
+export { CaldikClient, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caldik/client",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -18,9 +18,11 @@
   },
   "scripts": {
     "build": "tsdown",
+    "sync:api-contracts": "bun scripts/sync-api-contracts.ts",
     "test": "bun test"
   },
   "devDependencies": {
+    "@types/bun": "latest",
     "tsdown": "^0.22.3",
     "typescript": "^6.0.3"
   }