@caldik/client 0.1.0 → 0.1.2

package/README.md

@@ -1,81 +1,206 @@
-# 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,
-})
-```
-
-## Cart and discounts
-
-
-```ts
-const cart = caldik.cart.add({
-  productId: "PRODUCT_...",
-  productVariantId: "PRODUCT_VARIANT_...",
-  quantity: 1,
-})
-
-caldik.cart.updateQuantity(cart.items[0].id, 3)
-caldik.cart.remove(cart.items[0].id)
-```
-
-```ts
-await caldik.cart.applyDiscount("SAVE10")
-
-const result = await caldik.cart.checkout({
-  paymentMethod: "stripe",
-  items: [{ productId, productVariantId, quantity: 1 }],
-  termsAccepted: acceptedTermsCheckbox,
-  successUrl: "https://shop.example/success",
-  cancelUrl: "https://shop.example/cart",
-})
-```
-
-Use `caldik.discounts.check({ code, items })` when a cart should be managed by
-the application instead of the SDK.
-
-
-## Customer Logins
-
-Magic Code
-```ts
-await caldik.customer.requestLogin("customer@example.com")
-await caldik.customer.verifyLogin(code)
-```
-
-Username / Email Password ( if password login is enabled )
-```ts
-await caldik.customer.login({ username: "customer", password })
-```
-
-if you are logged in using magic code you can just do 
- - this to enroll the customers account into username / email password login ( password login needs to be enabled in the dashboard )
-```ts
-await caldik.customer.setPassword({ username: "customer", password })
-```
-
-## Payment methods and Settings
-
-```ts
-const { settings: loginSettings } = await caldik.customer.settings.get()
-const { settings: checkoutSettings } = await caldik.checkout.settings.get()
-const { paymentMethods } = await caldik.checkout.paymentmethods.list()
+# Caldik SDK
+
+The official Caldik SDK for interacting with Caldik storefronts, products, carts, checkouts, and customer accounts.
+
+## Caldik-hosted Storefront
+
+No credentials or store configuration are required when running inside a Caldik-hosted storefront.
+
+```ts
+import { CaldikClient } from "@caldik/client"
+
+const caldik = new CaldikClient()
+
+const { products } = await caldik.products.list()
+```
+
+## External Server
+
+External integrations must explicitly provide a store ID and a private `sk_` API key.
+
+```ts
+import { CaldikClient } from "@caldik/client"
+
+const caldik = new CaldikClient({
+  storeId: "STORE_...",
+  apiKey: process.env.CALDIK_PRIVATE_API_KEY,
+})
+```
+
+## Cart and Discounts
+
+### Cart Management
+
+Add products to the cart, update quantities, or remove items.
+
+```ts
+const cart = caldik.cart.add({
+  productId: "PRODUCT_...",
+  productVariantId: "PRODUCT_VARIANT_...",
+  quantity: 1,
+})
+
+// Update item quantity
+caldik.cart.updateQuantity(cart.items[0].id, 3)
+
+// Remove an item
+caldik.cart.remove(cart.items[0].id)
+```
+
+### Apply Discounts
+
+Apply a discount code to the current cart.
+
+```ts
+await caldik.cart.applyDiscount("SAVE10")
+```
+
+### Checkout
+
+Create a checkout session using the current cart or explicitly provided items.
+
+```ts
+const result = await caldik.cart.checkout({
+  paymentMethod: "stripe",
+  items: [
+    {
+      productId,
+      productVariantId,
+      quantity: 1,
+    },
+  ],
+  termsAccepted: acceptedTermsCheckbox,
+  successUrl: "https://shop.example/success",
+  cancelUrl: "https://shop.example/cart",
+})
+```
+
+### Validate Discounts
+
+If your application manages its own cart instead of using the SDK's built-in cart management, validate discount codes directly.
+
+```ts
+const result = await caldik.discounts.check({
+  code,
+  items,
+})
+```
+
+## Customer Authentication
+
+Caldik supports email-based magic code authentication and optional password authentication.
+
+Username authentication is available through the **Customer Usernames** plugin.
+
+### Magic Code Login
+
+Customers can log in using a six-digit verification code sent to their email address.
+
+```ts
+// Send a six-digit verification code
+await caldik.customer.login("customer@example.com")
+
+// Verify the code
+await caldik.customer.login.verify(code)
+```
+
+### Email and Password Login
+
+Email and password authentication requires password login to be enabled in the store dashboard.
+
+```ts
+await caldik.customer.login({
+  email: "customer@example.com",
+  password,
+})
+```
+
+### Username and Password Login
+
+Username authentication requires the **Customer Usernames** plugin to be installed and enabled.
+
+Once installed, customers can authenticate using their username instead of their email address.
+
+```ts
+await caldik.customer.login({
+  username: "customer",
+  password,
+})
+```
+
+> **Note:** Username authentication requires both the Customer Usernames plugin and password authentication to be enabled.
+
+## Customer Registration
+
+Customers can register using their email address, with optional password and username support.
+
+All registrations require email verification before the account is activated.
+
+Password registration must be enabled in the store dashboard.
+
+### Email Registration
+
+Register a customer using their email address and password.
+
+```ts
+// Register a new customer
+await caldik.customer.register({
+  email: "customer@example.com",
+  password,
+})
+
+// Verify the email using the six-digit code
+await caldik.customer.register.verify(code)
+```
+
+### Email and Username Registration
+
+To register customers with a username, install and enable the **Customer Usernames** plugin.
+
+Once installed, the registration endpoint accepts an additional `username` field.
+
+```ts
+// Register a new customer with a username
+await caldik.customer.register({
+  email: "customer@example.com",
+  password,
+  username: "customer",
+})
+
+// Verify the email using the six-digit code
+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.
+
+### Customer Settings
+
+```ts
+const { settings: loginSettings } = await caldik.customer.settings.get()
+```
+
+### Checkout Settings
+
+```ts
+const { settings: checkoutSettings } = await caldik.checkout.settings.get()
+```
+
+### Available Payment Methods
+
+```ts
+const { paymentMethods } = await caldik.checkout.paymentmethods.list()
+```
+
+### Combined Example
+
+```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

@@ -139,16 +139,19 @@ interface ManualCommerceItem {
   unitAmount: string | number;
 }
 interface ProductCommerceItem {
+  customFields?: Record<string, string | number | boolean>;
   productId: string;
   productVariantId?: string;
   quantity?: number;
 }
 type CommerceItem = ManualCommerceItem | ProductCommerceItem;
 interface CreateOrderInput {
+  uiMode?: "hosted" | "elements";
+  returnUrl?: string;
   customerId?: string;
   email?: string;
   termsAccepted?: boolean;
-  paymentMethod: CheckoutPaymentProviderId;
+  paymentMethod?: CheckoutPaymentProviderId;
   items: CommerceItem[];
   discountCode?: string;
   successUrl?: string;
@@ -157,10 +160,8 @@ interface CreateOrderInput {
 interface StorefrontOrder {
   id: string;
   shortId: string;
-  displayId: string;
   customerId: string | null;
   paymentStatus: string;
-  fulfillmentStatus: string;
   subtotal: string;
   amount: string;
   discount: {
@@ -171,6 +172,8 @@ interface StorefrontOrder {
   currency: string;
 }
 interface CheckoutPayment {
+  clientSecret?: string;
+  publishableKey?: string;
   type: CheckoutPaymentProviderId;
   checkoutUrl?: string | null;
   checkoutSessionId?: string | null;
@@ -223,22 +226,52 @@ interface StoreWebhookEvent<TObject extends Record<string, unknown> = Record<str
 }
 interface CustomerLoginResponse {
   success: boolean;
-  message: string;
+  challengeId: string;
 }
 interface CustomerLoginVerifyResponse {
+  session?: {
+    token: string;
+    expiresAt: number;
+  };
   success: boolean;
+}
+interface CustomerPasswordResponse extends CustomerLoginVerifyResponse {
   customer: {
     id: string;
     shortId: string;
     displayId: string;
     email: string | null;
     status: string;
+    extensions?: Record<string, Record<string, string | number | boolean>>;
   };
 }
 interface CustomerPasswordInput {
+  /** A username from an installed identity plugin, or the customer's email. */
   username: string;
   password: string;
 }
+interface CustomerRegistrationInput {
+  email: string;
+  password?: string;
+  /** Available when the store installs Customer Usernames. */
+  username?: string;
+  [pluginField: string]: string | number | boolean | undefined;
+}
+interface CustomerRegistrationResponse extends CustomerLoginResponse {
+  expiresAt: number;
+}
+interface CustomerProfileResponse {
+  success: boolean;
+  customer: {
+    id: string;
+    email: string | null;
+    extensions?: Record<string, Record<string, string | number | boolean>>;
+  };
+  balances: Array<{
+    currency: string;
+    amount: string;
+  }>;
+}
 interface CustomerLoginSettings {
   passwordEnabled: boolean;
 }
@@ -247,6 +280,9 @@ interface CustomerLoginSettingsResponse {
   settings: CustomerLoginSettings;
 }
 interface CheckoutSettings {
+  termsUrl?: string | null;
+  refundPolicyUrl?: string | null;
+  embedStripeMode: "elements" | "hosted" | "popup";
   requireEmail: boolean;
   requireTermsAcceptance: boolean;
 }
@@ -344,12 +380,21 @@ declare class CustomerApi {
   readonly settings: {
     get: () => Promise<CustomerLoginSettingsResponse>;
   };
+  readonly login: {
+    (email: string): 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>;
+  };
+  readonly register: {
+    (email: string): Promise<CustomerRegistrationResponse>;
+    (input: CustomerRegistrationInput): Promise<CustomerRegistrationResponse>;
+  } & {
+    /** Verify the email and atomically activate the account. Supports resuming after a reload. */verify: (code: string, challengeId?: string | undefined) => Promise<CustomerPasswordResponse>;
+  };
   constructor(client: CaldikHttpClient);
-  login(input: CustomerPasswordInput): Promise<CustomerLoginVerifyResponse>;
-  /** Set or reset credentials after signing in with an email code. Requires a customer session. */
-  setPassword(input: CustomerPasswordInput): Promise<CustomerLoginVerifyResponse>;
-  requestLogin(email: string): Promise<CustomerLoginResponse>;
-  verifyLogin(code: string): Promise<CustomerLoginVerifyResponse>;
+  /** Read the signed-in customer and their balances. */
+  me(): Promise<CustomerProfileResponse>;
 }
 //#endregion
 //#region src/subscriptions.d.ts
@@ -442,4 +487,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, 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, 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 };

package/dist/index.mjs

@@ -176,22 +176,52 @@ var CheckoutApi = class {
 var CustomerApi = class {
 	client;
 	settings;
+	login;
+	register;
 	constructor(client) {
 		this.client = client;
 		this.settings = { get: () => this.client.get("/customers/settings", void 0, { access: "public" }) };
-	}
-	login(input) {
-		return this.client.post("/customers/login/password", input, { access: "public" });
-	}
-	/** Set or reset credentials after signing in with an email code. Requires a customer session. */
-	setPassword(input) {
-		return this.client.post("/customers/password", input, { access: "public" });
-	}
-	requestLogin(email) {
-		return this.client.post("/customers/login", { email }, { access: "public" });
-	}
-	verifyLogin(code) {
-		return this.client.post("/customers/login/verify", { code }, { access: "public" });
+		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" });
+			pendingChallengeId = response.challengeId;
+			return response;
+		}
+		this.login = Object.assign(login, { 
+		/** Pass challengeId to resume a code request after reloading the page. */
+verify: async (code, challengeId = pendingChallengeId) => {
+			if (!/^\d{6}$/.test(code)) throw new Error("A six-digit login code is required");
+			if (!challengeId) throw new Error("Request a login code first or provide its challengeId");
+			const response = await client.post("/customers/login/verify", {
+				code,
+				challengeId
+			}, { access: "public" });
+			if (pendingChallengeId === challengeId) pendingChallengeId = void 0;
+			return response;
+		} });
+		let pendingRegistrationId;
+		async function register(input) {
+			const response = await client.post("/customers/register", typeof input === "string" ? { email: input } : input, { access: "public" });
+			pendingRegistrationId = response.challengeId;
+			return response;
+		}
+		this.register = Object.assign(register, { 
+		/** Verify the email and atomically activate the account. Supports resuming after a reload. */
+verify: async (code, challengeId = pendingRegistrationId) => {
+			if (!/^\d{6}$/.test(code)) throw new Error("A six-digit registration code is required");
+			if (!challengeId) throw new Error("Request a registration code first or provide its challengeId");
+			const response = await client.post("/customers/register/verify", {
+				code,
+				challengeId
+			}, { access: "public" });
+			if (pendingRegistrationId === challengeId) pendingRegistrationId = void 0;
+			return response;
+		} });
+	}
+	/** Read the signed-in customer and their balances. */
+	me() {
+		return this.client.get("/customers/me", void 0, { access: "public" });
 	}
 };
 //#endregion

package/package.json

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