@caldik/client 0.0.2 → 0.0.5

package/README.md

@@ -0,0 +1,24 @@
+# Caldik SDK
+
+## Caldik-hosted storefront
+
+No credentials or store configuration are required:
+
+```ts
+import { CaldikClient } from "@caldik/client"
+
+const caldik = new CaldikClient()
+const { products } = await caldik.products.list()
+```
+
+## External server
+
+External integrations explicitly provide the store ID and a private `sk_` API
+key:
+
+```ts
+const caldik = new CaldikClient({
+  storeId: "STORE_...",
+  apiKey: process.env.CALDIK_PRIVATE_API_KEY,
+})
+```

package/dist/index.d.mts

@@ -1,4 +1,12 @@
 //#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 +15,7 @@ interface Category {
   price: string;
   logo: string | null;
   banner: string | null;
+  metadata: CategoryMetadata[];
 }
 interface CategoriesResponse {
   success: boolean;
@@ -27,7 +36,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 +81,8 @@ interface Product {
   maximumQuantity: number | null;
   variants: ProductVariant[];
   tags: ProductTag[];
+  customFields: ProductCustomField[];
+  metadata: ProductMetadata[];
 }
 interface ProductVariant {
   id: string;
@@ -79,6 +94,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[];
@@ -175,19 +207,20 @@ interface CustomerLoginVerifyResponse {
 //#region src/internal/types.d.ts
 interface RequestOptions {
   edgeCache?: boolean;
+  /** Internal authorization policy. Protected hosted calls are the default. */
+  access?: "public" | "runtime";
 }
 //#endregion
 //#region src/internal/client.d.ts
-type CaldikTransport = "auto" | "browser" | "worker";
 type HttpClientOptions = {
   apiKey?: string;
   apiUrl?: string;
-  transport?: CaldikTransport;
+  storeId?: string;
 };
 declare class CaldikHttpClient {
   private readonly apiKey?;
   private readonly apiUrl;
-  private readonly transport;
+  private readonly storeId?;
   constructor(options?: HttpClientOptions);
   private baseUrl;
   private request;
@@ -250,13 +283,11 @@ declare class SubscriptionsApi {
 //#endregion
 //#region src/index.d.ts
 interface CaldikClientOptions {
-  /** API key for explicit external/browser integrations. */
+  /** Store ID for external servers. Hosted Workers receive it automatically. */
+  storeId?: string;
+  /** Private API key for external server integrations. Never use in browsers. */
   apiKey?: string;
-  /** @deprecated Use apiKey. Retained for backwards compatibility. */
-  publicApiKey?: string;
   apiUrl?: string;
-  /** Override automatic browser/Cloudflare Worker transport detection. */
-  transport?: CaldikTransport;
 }
 declare class CaldikClient {
   readonly categories: CategoriesApi;
@@ -269,4 +300,4 @@ declare class CaldikClient {
   constructor(options?: CaldikClientOptions);
 }
 //#endregion
-export { CaldikClient, CaldikClientOptions, type CaldikTransport, 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, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerLoginResponse, CustomerLoginVerifyResponse, ManualCommerceItem, OrderResponse, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StorefrontMetadata, StorefrontOrder, SubscriptionResponse };

package/dist/index.mjs

@@ -2,36 +2,47 @@
 const defaultApiUrl = typeof API_URL !== "undefined" ? API_URL : "https://api.caldik.com";
 //#endregion
 //#region src/internal/client.ts
+const STORE_ID_PATTERN = /^STORE_[a-f0-9]{32}$/i;
 function isBrowserRuntime() {
 	return typeof window !== "undefined" && typeof document !== "undefined";
 }
-function isCloudflareWorkerRuntime() {
-	return typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers";
+function boundRuntimeStoreId() {
+	const storeId = globalThis.process?.env?.CALDIK_STORE_ID?.trim();
+	return storeId && STORE_ID_PATTERN.test(storeId) ? storeId : null;
 }
 var CaldikHttpClient = class {
 	apiKey;
 	apiUrl;
-	transport;
+	storeId;
 	constructor(options = {}) {
-		this.apiKey = options.apiKey;
+		this.apiKey = options.apiKey?.trim() || void 0;
 		this.apiUrl = options.apiUrl || defaultApiUrl;
-		this.transport = options.transport || "auto";
+		this.storeId = options.storeId?.trim() || void 0;
+		if (this.apiKey && !this.apiKey.startsWith("sk_")) throw new Error("Caldik external integrations require a private sk_ API key");
+		if (this.storeId && !STORE_ID_PATTERN.test(this.storeId)) throw new Error("Caldik storeId is invalid");
+		if (isBrowserRuntime() && this.apiKey) throw new Error("Caldik private API keys cannot be used in browser code");
 	}
 	baseUrl() {
-		if (this.apiKey) return `${this.apiUrl.replace(/\/+$/, "")}/v1/storefront`;
-		if (this.transport === "browser" || this.transport === "auto" && isBrowserRuntime()) {
+		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 storeReference = location.hostname.trim().toLowerCase().replace(/\.$/, "");
+			if (!storeReference) throw new Error("Caldik browser transport requires a storefront hostname");
+			return `${this.apiUrl.replace(/\/+$/, "")}/v1/stores/${encodeURIComponent(storeReference)}`;
 		}
-		if (this.transport === "worker" || this.transport === "auto" && isCloudflareWorkerRuntime()) return `${this.apiUrl.replace(/\/+$/, "")}/v1/storefront`;
-		throw new Error("Caldik authentication is unavailable in this environment. Provide apiKey for an external integration, or set transport to \"browser\" or \"worker\" when environment detection is unavailable.");
+		const boundStoreId = boundRuntimeStoreId();
+		if (boundStoreId && this.storeId && boundStoreId !== this.storeId) throw new Error("Caldik storeId does not match the hosted runtime");
+		const storeId = this.storeId || boundStoreId;
+		if (!storeId) throw new Error("Caldik authentication is unavailable. External servers must provide storeId and a private apiKey.");
+		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) {
 		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 = {};
-		if (!isBrowserRuntime()) headers["User-Agent"] = "CaldikClient/0.0.1";
+		if (!isBrowserRuntime()) headers["User-Agent"] = "CaldikClient/0.0.2";
 		if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+		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, {
@@ -63,10 +74,10 @@ var CategoriesApi = class {
 		this.client = client;
 	}
 	list(limit) {
-		return this.client.get("/categories", limit ? { limit } : void 0);
+		return this.client.get("/categories", limit ? { limit } : void 0, { access: "public" });
 	}
 	get(categoryId) {
-		return this.client.get(`/categories/${categoryId}`);
+		return this.client.get(`/categories/${categoryId}`, void 0, { access: "public" });
 	}
 };
 //#endregion
@@ -77,10 +88,10 @@ var ProductsApi = class {
 		this.client = client;
 	}
 	list() {
-		return this.client.get("/products");
+		return this.client.get("/products", void 0, { access: "public" });
 	}
 	get(productId) {
-		return this.client.get(`/products/${productId}`);
+		return this.client.get(`/products/${productId}`, void 0, { access: "public" });
 	}
 };
 //#endregion
@@ -91,7 +102,7 @@ var ReviewsApi = class {
 		this.client = client;
 	}
 	list(limit) {
-		return this.client.get("/reviews", limit ? { limit } : void 0);
+		return this.client.get("/reviews", limit ? { limit } : void 0, { access: "public" });
 	}
 };
 //#endregion
@@ -102,7 +113,7 @@ var StoreApi = class {
 		this.client = client;
 	}
 	get() {
-		return this.client.get("");
+		return this.client.get("", void 0, { access: "public" });
 	}
 };
 //#endregion
@@ -113,10 +124,10 @@ var CheckoutApi = class {
 		this.client = client;
 	}
 	create(input) {
-		return this.client.post("/checkout", input);
+		return this.client.post("/checkouts", input, { access: "public" });
 	}
 	payWithBalance(orderId) {
-		return this.client.post(`/checkout/${encodeURIComponent(orderId)}/balance-payment`);
+		return this.client.post(`/checkouts/${encodeURIComponent(orderId)}/balance-payment`, void 0, { access: "public" });
 	}
 };
 //#endregion
@@ -127,10 +138,10 @@ var CustomerApi = class {
 		this.client = client;
 	}
 	requestLogin(email) {
-		return this.client.post("/customer/login", { email });
+		return this.client.post("/customers/login", { email }, { access: "public" });
 	}
 	verifyLogin(code) {
-		return this.client.post("/customer/login/verify", { code });
+		return this.client.post("/customers/login/verify", { code }, { access: "public" });
 	}
 };
 //#endregion
@@ -141,7 +152,7 @@ var SubscriptionsApi = class {
 		this.client = client;
 	}
 	create(input) {
-		return this.client.post("/subscriptions", input);
+		return this.client.post("/subscriptions", input, { access: "public" });
 	}
 };
 //#endregion
@@ -156,9 +167,9 @@ var CaldikClient = class {
 	subscriptions;
 	constructor(options = {}) {
 		const client = new CaldikHttpClient({
-			apiKey: options.apiKey ?? options.publicApiKey,
+			apiKey: options.apiKey,
 			apiUrl: options.apiUrl,
-			transport: options.transport
+			storeId: options.storeId
 		});
 		this.categories = new CategoriesApi(client);
 		this.products = new ProductsApi(client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caldik/client",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -21,6 +21,7 @@
     "test": "bun test"
   },
   "devDependencies": {
+    "@types/bun": "latest",
     "tsdown": "^0.22.3",
     "typescript": "^6.0.3"
   }