Dynamic Commerce
X ยท
LinkedIn
> [!WARNING]
> This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.
# Customers Module
๐ **Documentation:** [86d.app/docs/modules/customers](https://86d.app/docs/modules/customers)
Customer profile and address management. Authenticated customers can view and edit their profile and saved addresses. Admins have full read/write access to all customer records.
## Installation
```sh
npm install @86d-app/customers
```
## Usage
```ts
import customers from "@86d-app/customers";
const module = customers({
autoCreateOnSignup: true,
});
```
## Configuration
| Option | Type | Default | Description |
|---|---|---|---|
| `autoCreateOnSignup` | `boolean` | `true` | Automatically create a customer record when a user signs up |
## Store Endpoints
All store endpoints require an authenticated session.
| Method | Path | Description |
|---|---|---|
| `GET` | `/customers/me` | Get the authenticated customer's profile |
| `PUT` | `/customers/me/update` | Update the authenticated customer's profile |
| `GET` | `/customers/me/addresses` | List all addresses for the authenticated customer |
| `POST` | `/customers/me/addresses/create` | Add a new address |
| `PUT` | `/customers/me/addresses/:id` | Update an existing address |
| `DELETE` | `/customers/me/addresses/:id/delete` | Delete an address |
## Admin Endpoints
| Method | Path | Description |
|---|---|---|
| `GET` | `/admin/customers` | List all customers (paginated, searchable) |
| `GET` | `/admin/customers/:id` | Get a customer by ID |
| `PUT` | `/admin/customers/:id/update` | Update a customer |
| `DELETE` | `/admin/customers/:id/delete` | Delete a customer |
## Controller API
```ts
interface CustomerController {
/** Look up a customer by their ID */
getById(id: string): Promise;
/** Look up a customer by their email address */
getByEmail(email: string): Promise;
/** Create a new customer record */
create(params: {
id?: string;
email: string;
firstName: string;
lastName: string;
phone?: string;
dateOfBirth?: Date;
metadata?: Record;
}): Promise;
/** Update an existing customer's profile fields */
update(
id: string,
params: {
firstName?: string;
lastName?: string;
phone?: string | null;
dateOfBirth?: Date | null;
metadata?: Record;
},
): Promise;
/** Hard-delete a customer */
delete(id: string): Promise;
/** List customers with optional search and pagination */
list(params: {
limit?: number;
offset?: number;
search?: string;
}): Promise<{ customers: Customer[]; total: number }>;
/** Get all saved addresses for a customer */
listAddresses(customerId: string): Promise;
/** Get a single address by ID */
getAddress(id: string): Promise;
/** Add an address to a customer's account */
createAddress(params: {
customerId: string;
type?: "billing" | "shipping";
firstName: string;
lastName: string;
company?: string;
line1: string;
line2?: string;
city: string;
state: string;
postalCode: string;
country: string; // ISO 3166-1 alpha-2 (e.g. "US")
phone?: string;
isDefault?: boolean;
}): Promise;
/** Update fields on an existing address */
updateAddress(
id: string,
params: {
type?: "billing" | "shipping";
firstName?: string;
lastName?: string;
company?: string | null;
line1?: string;
line2?: string | null;
city?: string;
state?: string;
postalCode?: string;
country?: string;
phone?: string | null;
isDefault?: boolean;
},
): Promise;
/** Remove an address */
deleteAddress(id: string): Promise;
/**
* Mark an address as default for its type.
* Automatically clears the previous default of the same type.
*/
setDefaultAddress(
customerId: string,
addressId: string,
): Promise;
}
```
## Types
```ts
interface Customer {
id: string;
email: string;
firstName: string;
lastName: string;
phone?: string;
dateOfBirth?: Date;
metadata?: Record;
createdAt: Date;
updatedAt: Date;
}
interface CustomerAddress {
id: string;
customerId: string;
type: "billing" | "shipping";
firstName: string;
lastName: string;
company?: string;
line1: string;
line2?: string;
city: string;
state: string;
postalCode: string;
country: string; // ISO 3166-1 alpha-2
phone?: string;
isDefault: boolean;
createdAt: Date;
updatedAt: Date;
}
```
## Store Components
### AccountProfile
Displays the authenticated customer's profile (name, email, phone) with inline editing support for updating personal information.
#### Props
None. The component manages its own state and fetches data via the module client.
#### Usage in MDX
```mdx
```
Use this component on a customer account or profile settings page.
### AddressBook
Manages the authenticated customer's saved addresses with full CRUD support for creating, editing, and deleting billing and shipping addresses.
#### Props
None. The component manages its own state and fetches data via the module client.
#### Usage in MDX
```mdx
```
Use this component on a customer account page to let users manage their saved addresses.
### LoyaltyCard
Displays the authenticated customer's loyalty points balance, tier, and transaction history.
#### Props
None. The component manages its own state and fetches data via the module client.
#### Usage in MDX
```mdx
```
Use this component on a customer account or rewards page to show loyalty program status and point history.
## Notes
- Store endpoints resolve the customer ID from the active session (`ctx.context.session?.user.id`). Unauthenticated requests are rejected.
- Address ownership is verified before any update or delete operation โ customers cannot modify each other's addresses.
- `setDefaultAddress` is idempotent: calling it on an already-default address is a no-op.
- Each customer can have one default billing address and one default shipping address independently.