@caldik/client 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,15 @@
 
 The official Caldik SDK for interacting with Caldik storefronts, products, carts, checkouts, and customer accounts.
 
-## Caldik-hosted Storefront
+## Installation
+
+```bash
+npm install @caldik/client
+```
+
+## Getting Started
+
+### Caldik-hosted Storefront
 
 No credentials or store configuration are required when running inside a Caldik-hosted storefront.
 
@@ -14,7 +22,7 @@ const caldik = new CaldikClient()
 const { products } = await caldik.products.list()
 ```
 
-## External Server
+### External Server
 
 External integrations must explicitly provide a store ID and a private `sk_` API key.
 
@@ -27,23 +35,71 @@ const caldik = new CaldikClient({
 })
 ```
 
+> **Security:** Private API keys must only be used in trusted server-side environments. Never expose `sk_` keys in client-side code.
+
+## Orders and Items
+
+### Categories
+
+Retrieve categories associated with the current store.
+
+**Basic usage**
+
+```ts
+const { categories } = await caldik.categories.list()
+```
+
+**Limit results**
+
+Pass a number to limit the number of categories returned.
+
+```ts
+const { categories } = await caldik.categories.list(20)
+```
+
+**Advanced usage**
+
+Use an options object to configure the limit and request additional fields.
+
+```ts
+const { categories } = await caldik.categories.list({
+  limit: 20,
+  include: ["productCount", "startingPrice"],
+})
+```
+
+The following fields are omitted by default unless explicitly requested using `include`:
+
+| Field | Description |
+|---|---|
+| `productCount` | Number of products associated with the category. |
+| `startingPrice` | Lowest available product price in the category, in cents. |
+
 ## Cart and Discounts
 
 ### Cart Management
 
 Add products to the cart, update quantities, or remove items.
 
+**Add an item**
+
 ```ts
 const cart = caldik.cart.add({
   productId: "PRODUCT_...",
   productVariantId: "PRODUCT_VARIANT_...",
   quantity: 1,
 })
+```
+
+**Update item quantity**
 
-// Update item quantity
+```ts
 caldik.cart.updateQuantity(cart.items[0].id, 3)
+```
 
-// Remove an item
+**Remove an item**
+
+```ts
 caldik.cart.remove(cart.items[0].id)
 ```
 
@@ -96,11 +152,24 @@ Username authentication is available through the **Customer Usernames** plugin.
 
 Customers can log in using a six-digit verification code sent to their email address.
 
+**Send a verification code**
+
 ```ts
-// Send a six-digit verification code
 await caldik.customer.login("customer@example.com")
+```
+
+Alternatively, use an options object to configure the session.
+
+```ts
+await caldik.customer.login({
+  email: "customer@example.com",
+  rememberMe: true, // Optional, defaults to false
+})
+```
+
+**Verify the code**
 
-// Verify the code
+```ts
 await caldik.customer.login.verify(code)
 ```
 
@@ -112,6 +181,7 @@ Email and password authentication requires password login to be enabled in the s
 await caldik.customer.login({
   email: "customer@example.com",
   password,
+  rememberMe: true, // Optional, defaults to false
 })
 ```
 
@@ -125,11 +195,58 @@ Once installed, customers can authenticate using their username instead of their
 await caldik.customer.login({
   username: "customer",
   password,
+  rememberMe: true, // Optional, defaults to false
 })
 ```
 
 > **Note:** Username authentication requires both the Customer Usernames plugin and password authentication to be enabled.
 
+### Session Duration
+
+All customer authentication methods support the optional `rememberMe` parameter.
+
+| `rememberMe` | Session Duration |
+|---|---|
+| `false` (default) | 24 hours |
+| `true` | 30 days |
+
+Omit `rememberMe` to use the default session duration.
+
+### Session Check
+
+Retrieve the current customer's authentication status, account details, and session expiration.
+
+```ts
+const {
+  authenticated,
+  customer,
+  expiresAt,
+} = await caldik.customer.session()
+```
+
+### Password Reset
+
+Customers can reset their passwords using a verification code sent to their email address.
+
+**Request a password reset**
+
+```ts
+const { challengeId } =
+  await caldik.customer.password.requestReset(email)
+```
+
+Password reset codes expire after **10 minutes**.
+
+**Reset the password**
+
+```ts
+await caldik.customer.password.reset({
+  challengeId,
+  code,
+  password: newPassword,
+})
+```
+
 ## Customer Registration
 
 Customers can register using their email address, with optional password and username support.
@@ -142,14 +259,18 @@ Password registration must be enabled in the store dashboard.
 
 Register a customer using their email address and password.
 
+**Register a customer**
+
 ```ts
-// Register a new customer
 await caldik.customer.register({
   email: "customer@example.com",
   password,
 })
+```
 
-// Verify the email using the six-digit code
+**Verify the email address**
+
+```ts
 await caldik.customer.register.verify(code)
 ```
 
@@ -159,15 +280,19 @@ To register customers with a username, install and enable the **Customer Usernam
 
 Once installed, the registration endpoint accepts an additional `username` field.
 
+**Register a customer with a username**
+
 ```ts
-// Register a new customer with a username
 await caldik.customer.register({
   email: "customer@example.com",
   password,
   username: "customer",
 })
+```
+
+**Verify the email address**
 
-// Verify the email using the six-digit code
+```ts
 await caldik.customer.register.verify(code)
 ```
 
@@ -179,28 +304,36 @@ Retrieve customer authentication settings, checkout configuration, and available
 
 ### Customer Settings
 
+Retrieve the store's customer authentication settings.
+
 ```ts
 const { settings: loginSettings } = await caldik.customer.settings.get()
 ```
 
 ### Checkout Settings
 
+Retrieve the store's checkout configuration.
+
 ```ts
 const { settings: checkoutSettings } = await caldik.checkout.settings.get()
 ```
 
 ### Available Payment Methods
 
+Retrieve the payment methods available for checkout.
+
 ```ts
 const { paymentMethods } = await caldik.checkout.paymentmethods.list()
 ```
 
 ### Combined Example
 
+Retrieve customer settings, checkout settings, and available payment methods together.
+
 ```ts
 const { settings: loginSettings } = await caldik.customer.settings.get()
 
 const { settings: checkoutSettings } = await caldik.checkout.settings.get()
 
 const { paymentMethods } = await caldik.checkout.paymentmethods.list()
-```
+```

package/dist/index.d.mts

@@ -24,7 +24,10 @@ interface Category {
   name: string;
   slug: string;
   description: string;
-  price: string;
+  /** Present when startingPrice is included. Prefer startingPrice. */
+  price?: string;
+  productCount?: number;
+  startingPrice?: string | null;
   logo: string | null;
   banner: string | null;
   metadata: CategoryMetadata[];
@@ -33,6 +36,11 @@ interface CategoriesResponse {
   success: boolean;
   categories: Category[];
 }
+type CategoryInclude = "productCount" | "startingPrice" | "product count" | "starting price";
+interface CategoryListOptions {
+  limit?: number;
+  include?: readonly CategoryInclude[];
+}
 interface CategoryProduct {
   id: string;
   name: string;
@@ -245,10 +253,41 @@ interface CustomerPasswordResponse extends CustomerLoginVerifyResponse {
     extensions?: Record<string, Record<string, string | number | boolean>>;
   };
 }
-interface CustomerPasswordInput {
-  /** A username from an installed identity plugin, or the customer's email. */
+type CustomerPasswordInput = ({
   username: string;
+  email?: never;
+} | {
+  email: string;
+  username?: never;
+}) & {
   password: string;
+  rememberMe?: boolean;
+};
+interface CustomerEmailLoginInput {
+  email: string;
+  rememberMe?: boolean;
+}
+interface CustomerSessionResponse {
+  success: boolean;
+  authenticated: boolean;
+  customer: {
+    id: string;
+    email: string | null;
+  } | null;
+  expiresAt: number | null;
+}
+interface CustomerPasswordResetResponse extends CustomerLoginResponse {
+  expiresAt: number;
+  message: string;
+}
+interface CustomerPasswordResetInput {
+  challengeId?: string;
+  code: string;
+  password: string;
+}
+interface CustomerPasswordResetVerifyResponse {
+  success: boolean;
+  message: string;
 }
 interface CustomerRegistrationInput {
   email: string;
@@ -334,7 +373,7 @@ declare class CaldikHttpClient {
 declare class CategoriesApi {
   private client;
   constructor(client: CaldikHttpClient);
-  list(limit?: number): Promise<CategoriesResponse>;
+  list(options?: number | CategoryListOptions): Promise<CategoriesResponse>;
   get(categoryId: string): Promise<CategoryResponse>;
 }
 //#endregion
@@ -381,7 +420,10 @@ declare class CustomerApi {
     get: () => Promise<CustomerLoginSettingsResponse>;
   };
   readonly login: {
-    (email: string): Promise<CustomerLoginResponse>;
+    (email: string, options?: {
+      rememberMe?: boolean;
+    }): Promise<CustomerLoginResponse>;
+    (input: CustomerEmailLoginInput): Promise<CustomerLoginResponse>;
     (input: CustomerPasswordInput): Promise<CustomerPasswordResponse>;
   } & {
     /** Pass challengeId to resume a code request after reloading the page. */verify: (code: string, challengeId?: string | undefined) => Promise<CustomerLoginVerifyResponse>;
@@ -392,7 +434,13 @@ declare class CustomerApi {
   } & {
     /** Verify the email and atomically activate the account. Supports resuming after a reload. */verify: (code: string, challengeId?: string | undefined) => Promise<CustomerPasswordResponse>;
   };
+  readonly password: {
+    requestReset: (email: string) => Promise<CustomerPasswordResetResponse>;
+    reset: (input: CustomerPasswordResetInput) => Promise<CustomerPasswordResetVerifyResponse>;
+  };
   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>;
 }
@@ -487,4 +535,4 @@ declare class CaldikClient {
   constructor(options?: CaldikClientOptions);
 }
 //#endregion
-export { AppliedDiscount, CaldikClient, CaldikClientOptions, CartApi, CartCheckoutInput, CartDiscount, CartItem, CartSnapshot, CategoriesResponse, Category, CategoryDetails, CategoryMetadata, CategoryProduct, CategoryResponse, CheckDiscountInput, CheckoutPayment, CheckoutPaymentMethod, CheckoutPaymentMethodsResponse, CheckoutPaymentProviderId, CheckoutSettings, CheckoutSettingsResponse, CommerceItem, CreateOrderInput, CreateSubscriptionInput, CustomerLoginResponse, CustomerLoginSettings, CustomerLoginSettingsResponse, CustomerLoginVerifyResponse, CustomerPasswordInput, CustomerPasswordResponse, CustomerProfileResponse, CustomerRegistrationInput, CustomerRegistrationResponse, DiscountQuoteResponse, DiscountsApi, ManualCommerceItem, OrderResponse, PaymentProviderId, Product, ProductCommerceItem, ProductCustomField, ProductCustomFieldInputType, ProductCustomFieldOption, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreWebhookEvent, StoreWebhookEventName, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };
+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, ProductMetadata, ProductResponse, ProductTag, ProductVariant, ProductsResponse, Review, ReviewsResponse, Store, StoreResponse, StoreWebhookEvent, StoreWebhookEventName, StorefrontMetadata, StorefrontOrder, SubscriptionPaymentProviderId, SubscriptionResponse, checkoutPaymentProviderIds, paymentProviderIds, storeWebhookEventNames, subscriptionPaymentProviderIds };

package/dist/index.mjs

@@ -110,8 +110,12 @@ var CategoriesApi = class {
 	constructor(client) {
 		this.client = client;
 	}
-	list(limit) {
-		return this.client.get("/categories", limit ? { limit } : void 0, { access: "public" });
+	list(options) {
+		const { limit, include } = typeof options === "number" ? { limit: options } : options ?? {};
+		return this.client.get("/categories", {
+			...limit !== void 0 ? { limit } : {},
+			...include?.length ? { include: include.join(",") } : {}
+		}, { access: "public" });
 	}
 	get(categoryId) {
 		return this.client.get(`/categories/${categoryId}`, void 0, { access: "public" });
@@ -178,13 +182,36 @@ var CustomerApi = class {
 	settings;
 	login;
 	register;
+	password;
 	constructor(client) {
 		this.client = client;
 		this.settings = { get: () => this.client.get("/customers/settings", void 0, { access: "public" }) };
+		let pendingResetId;
+		this.password = {
+			requestReset: async (email) => {
+				const response = await client.post("/customers/password/reset", { email }, { access: "public" });
+				pendingResetId = response.challengeId;
+				return response;
+			},
+			reset: async (input) => {
+				const challengeId = input.challengeId ?? pendingResetId;
+				if (!challengeId) throw new Error("Request a password reset first or provide its challengeId");
+				if (!/^\d{6}$/.test(input.code)) throw new Error("A six-digit reset code is required");
+				const response = await client.post("/customers/password/reset/verify", {
+					...input,
+					challengeId
+				}, { access: "public" });
+				if (pendingResetId === challengeId) pendingResetId = void 0;
+				return response;
+			}
+		};
 		let pendingChallengeId;
-		async function login(input) {
-			if (typeof input !== "string") return client.post("/customers/login/password", input, { access: "public" });
-			const response = await client.post("/customers/login", { email: input }, { access: "public" });
+		async function login(input, options) {
+			if (typeof input !== "string" && "password" in input) return client.post("/customers/login/password", input, { access: "public" });
+			const response = await client.post("/customers/login", typeof input === "string" ? {
+				email: input,
+				...options
+			} : input, { access: "public" });
 			pendingChallengeId = response.challengeId;
 			return response;
 		}
@@ -219,6 +246,10 @@ verify: async (code, challengeId = pendingRegistrationId) => {
 			return response;
 		} });
 	}
+	/** Check a store-scoped session without raising an error for signed-out customers. */
+	session() {
+		return this.client.get("/customers/session", void 0, { access: "public" });
+	}
 	/** Read the signed-in customer and their balances. */
 	me() {
 		return this.client.get("/customers/me", void 0, { access: "public" });

package/package.json

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