@caldik/client 0.0.1 → 0.0.4

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

@@ -5,8 +5,8 @@ interface Category {
   slug: string;
   description: string;
   price: string;
-  logo: string;
-  banner: string;
+  logo: string | null;
+  banner: string | null;
 }
 interface CategoriesResponse {
   success: boolean;
@@ -21,8 +21,8 @@ interface CategoryProduct {
     color: string;
   }[];
   price: string;
-  logo: string;
-  banner: string;
+  logo: string | null;
+  banner: string | null;
 }
 interface CategoryDetails {
   id: string;
@@ -56,20 +56,144 @@ interface ReviewsResponse {
 interface Product {
   id: string;
   name: string;
-  price: number;
+  type: string;
+  slug: string;
+  description: string;
+  price: string;
+  logo: string | null;
+  banner: string | null;
+  videoUrl: string | null;
+  deliveryType: string;
+  minimumQuantity: number | null;
+  maximumQuantity: number | null;
+  variants: ProductVariant[];
+  tags: ProductTag[];
+}
+interface ProductVariant {
+  id: string;
+  name: string;
+  price: string;
+  compareAtPrice: string | null;
+}
+interface ProductTag {
+  label: string;
+  color: string;
+}
+interface ProductsResponse {
+  success: boolean;
+  products: Product[];
+}
+interface ProductResponse {
+  success: boolean;
+  product: Product;
+}
+interface ManualCommerceItem {
+  name: string;
+  description?: string;
+  quantity?: number;
+  unitAmount: string | number;
+}
+interface ProductCommerceItem {
+  productId: string;
+  productVariantId?: string;
+  quantity?: number;
+}
+type CommerceItem = ManualCommerceItem | ProductCommerceItem;
+interface CreateOrderInput {
+  customerId?: string;
+  email?: string;
+  paymentMethod: "customer_balance" | "stripe" | "ovgc";
+  items: CommerceItem[];
+  successUrl?: string;
+  cancelUrl?: string;
+}
+interface StorefrontOrder {
+  id: string;
+  shortId: string;
+  displayId: string;
+  customerId: string | null;
+  paymentStatus: string;
+  fulfillmentStatus: string;
+  amount: string;
+  currency: string;
+}
+interface CheckoutPayment {
+  type: "customer_balance" | "stripe" | "ovgc";
+  checkoutUrl?: string | null;
+  checkoutSessionId?: string | null;
+  balanceAfter?: string;
+}
+interface OrderResponse {
+  success: boolean;
+  order: StorefrontOrder;
+  payment: CheckoutPayment | null;
+}
+interface CreateSubscriptionInput {
+  customerId?: string;
+  email?: string;
+  items: CommerceItem[];
+  billingInterval: "day" | "week" | "month" | "year";
+  billingIntervalCount?: number;
+  trialDays?: number;
+  successUrl: string;
+  cancelUrl: string;
+}
+interface SubscriptionResponse {
+  success: boolean;
+  subscription: {
+    id: string;
+    shortId: string;
+    displayId: string;
+    customerId: string;
+    status: string;
+    billingInterval: string;
+    billingIntervalCount: number;
+    amount: string;
+    currency: string;
+  };
+  payment: {
+    type: "stripe";
+    checkoutUrl: string;
+    checkoutSessionId: string;
+  };
+}
+interface CustomerLoginResponse {
+  success: boolean;
+  message: string;
+}
+interface CustomerLoginVerifyResponse {
+  success: boolean;
+  customer: {
+    id: string;
+    shortId: string;
+    displayId: string;
+    email: string;
+    status: string;
+  };
 }
 //#endregion
 //#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 HttpClientOptions = {
+  apiKey?: string;
+  apiUrl?: string;
+  storeId?: string;
+};
 declare class CaldikHttpClient {
-  private publicKey?;
-  private apiUrl;
-  constructor(publicKey?: string | undefined, apiUrl?: string);
+  private readonly apiKey?;
+  private readonly apiUrl;
+  private readonly storeId?;
+  constructor(options?: HttpClientOptions);
+  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>;
 }
 //#endregion
 //#region src/categories.d.ts
@@ -84,8 +208,8 @@ declare class CategoriesApi {
 declare class ProductsApi {
   private client;
   constructor(client: CaldikHttpClient);
-  list(): Promise<Product[]>;
-  get(productId: string): Promise<Product>;
+  list(): Promise<ProductsResponse>;
+  get(productId: string): Promise<ProductResponse>;
 }
 //#endregion
 //#region src/reviews.d.ts
@@ -102,9 +226,35 @@ declare class StoreApi {
   get(): Promise<StoreResponse>;
 }
 //#endregion
+//#region src/checkout.d.ts
+declare class CheckoutApi {
+  private client;
+  constructor(client: CaldikHttpClient);
+  create(input: CreateOrderInput): Promise<OrderResponse>;
+  payWithBalance(orderId: string): Promise<OrderResponse>;
+}
+//#endregion
+//#region src/customer.d.ts
+declare class CustomerApi {
+  private client;
+  constructor(client: CaldikHttpClient);
+  requestLogin(email: string): Promise<CustomerLoginResponse>;
+  verifyLogin(code: string): Promise<CustomerLoginVerifyResponse>;
+}
+//#endregion
+//#region src/subscriptions.d.ts
+declare class SubscriptionsApi {
+  private client;
+  constructor(client: CaldikHttpClient);
+  create(input: CreateSubscriptionInput): Promise<SubscriptionResponse>;
+}
+//#endregion
 //#region src/index.d.ts
 interface CaldikClientOptions {
-  publicApiKey?: string;
+  /** 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;
   apiUrl?: string;
 }
 declare class CaldikClient {
@@ -112,7 +262,10 @@ declare class CaldikClient {
   readonly products: ProductsApi;
   readonly reviews: ReviewsApi;
   readonly store: StoreApi;
+  readonly checkout: CheckoutApi;
+  readonly customer: CustomerApi;
+  readonly subscriptions: SubscriptionsApi;
   constructor(options?: CaldikClientOptions);
 }
 //#endregion
-export { CaldikClient, CaldikClientOptions };
+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 };

package/dist/index.mjs

@@ -2,29 +2,67 @@
 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 boundRuntimeStoreId() {
+	const storeId = globalThis.process?.env?.CALDIK_STORE_ID?.trim();
+	return storeId && STORE_ID_PATTERN.test(storeId) ? storeId : null;
+}
 var CaldikHttpClient = class {
-	publicKey;
+	apiKey;
 	apiUrl;
-	constructor(publicKey, apiUrl = defaultApiUrl) {
-		this.publicKey = publicKey;
-		this.apiUrl = apiUrl;
+	storeId;
+	constructor(options = {}) {
+		this.apiKey = options.apiKey?.trim() || void 0;
+		this.apiUrl = options.apiUrl || defaultApiUrl;
+		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 (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 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 get(path, params, options) {
-		const baseUrl = this.apiUrl.replace(/\/+$/, "");
-		const url = new URL(`${baseUrl}/v1${path}`);
+	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 = {
-			"User-Agent": "CaldikClient/0.0.1",
-			...this.publicKey && { Authorization: `Bearer ${this.publicKey}` }
-		};
+		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";
+		if (input !== void 0) headers["Content-Type"] = "application/json";
 		if (options?.edgeCache) headers["X-Cache-Policy"] = "public";
 		const response = await fetch(url, {
+			method,
 			headers,
-			cache: "default"
+			...input !== void 0 ? { body: JSON.stringify(input) } : {},
+			cache: "default",
+			credentials: "include"
 		});
-		if (!response.ok) throw new Error(response.statusText);
+		if (!response.ok) {
+			const error = await response.clone().json().catch(() => null);
+			const message = typeof error?.message === "string" && error.message ? error.message : `${response.status} ${response.statusText}`.trim();
+			throw new Error(message);
+		}
 		return response.json();
 	}
+	get(path, params, options) {
+		return this.request("GET", path, void 0, params, options);
+	}
+	post(path, input, options) {
+		return this.request("POST", path, input, void 0, options);
+	}
 };
 //#endregion
 //#region src/categories.ts
@@ -34,10 +72,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
@@ -48,10 +86,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
@@ -62,7 +100,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
@@ -73,7 +111,46 @@ var StoreApi = class {
 		this.client = client;
 	}
 	get() {
-		return this.client.get("");
+		return this.client.get("", void 0, { access: "public" });
+	}
+};
+//#endregion
+//#region src/checkout.ts
+var CheckoutApi = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	create(input) {
+		return this.client.post("/checkouts", input, { access: "public" });
+	}
+	payWithBalance(orderId) {
+		return this.client.post(`/checkouts/${encodeURIComponent(orderId)}/balance-payment`, void 0, { access: "public" });
+	}
+};
+//#endregion
+//#region src/customer.ts
+var CustomerApi = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	requestLogin(email) {
+		return this.client.post("/customers/login", { email }, { access: "public" });
+	}
+	verifyLogin(code) {
+		return this.client.post("/customers/login/verify", { code }, { access: "public" });
+	}
+};
+//#endregion
+//#region src/subscriptions.ts
+var SubscriptionsApi = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	create(input) {
+		return this.client.post("/subscriptions", input, { access: "public" });
 	}
 };
 //#endregion
@@ -83,12 +160,22 @@ var CaldikClient = class {
 	products;
 	reviews;
 	store;
+	checkout;
+	customer;
+	subscriptions;
 	constructor(options = {}) {
-		const client = new CaldikHttpClient(options.publicApiKey, options.apiUrl);
+		const client = new CaldikHttpClient({
+			apiKey: options.apiKey,
+			apiUrl: options.apiUrl,
+			storeId: options.storeId
+		});
 		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.subscriptions = new SubscriptionsApi(client);
 	}
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caldik/client",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -17,7 +17,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown"
+    "build": "tsdown",
+    "test": "bun test"
   },
   "devDependencies": {
     "tsdown": "^0.22.3",