@01.software/sdk 0.12.1 → 0.13.0

package/README.md

@@ -21,7 +21,7 @@ pnpm add @01.software/sdk
 - Automatic retry with exponential backoff (non-retryable: 401, 403, 404, 422)
 - Webhook handling with HMAC-SHA256 signature verification
 - Sub-path imports (`./webhook`, `./realtime`, `./ui/*`) for tree-shaking
-- Type-safe read-only `from()` for Client (compile-time write prevention)
+- Type-safe read-only `collections.from()` for Client (compile-time write prevention)
 
 ### Sub-path Imports
 
@@ -59,7 +59,7 @@ const client = createClient({
 })
 
 // Query data (returns Payload native response)
-const { docs } = await client.from('products').find({
+const { docs } = await client.collections.from('products').find({
   limit: 10,
   where: { status: { equals: 'published' } },
 })
@@ -76,18 +76,18 @@ const client = createServerClient({
 })
 
 // Create order (server only)
-const order = await client.api.createOrder({
+const order = await server.commerce.orders.create({
   orderNumber: generateOrderNumber(),
   customerSnapshot: { email: 'user@example.com' },
   shippingAddress: { recipientName: 'John', phone: '010-1234-5678', postalCode: '12345', address1: 'Seoul', address2: 'Apt 101' },
-  orderProducts: [...],
+  orderItems: [...],
   totalAmount: 10000,
-  paymentId: 'pay_123', // optional (omit for free orders)
+  pgPaymentId: 'pay_123', // optional (omit for free orders)
   discountCode: 'WELCOME10', // optional
 })
 
 // SSR prefetch (server)
-await client.query.prefetchQuery({
+await server.query.prefetchQuery({
   collection: 'products',
   options: { limit: 10 },
 })
@@ -101,6 +101,12 @@ await client.query.prefetchQuery({
 const client = createClient({
   publishableKey: string, // Required
 })
+
+const server = createServerClient({
+  publishableKey: string,
+  secretKey: string,      // sk01_... or pat01_...
+  tenantId: string,       // required when secretKey is pat01_
+})
 ```
 
 | Option           | Type     | Description                  |
@@ -115,13 +121,13 @@ API URL은 환경변수로 오버라이드 가능합니다:
 
 ### Query Builder
 
-Access collections via `client.from(collection)` method.
+Access collections via `client.collections.from(slug)`.
 
-> **Note:** `Client.from()` returns a `ReadOnlyQueryBuilder` (only `find`, `findById`, `count`, `findMetadata`, `findMetadataById`). Write operations (`create`, `update`, `remove`, `updateMany`, `removeMany`) are only available on `ServerClient.from()`.
+> **Note:** `client.collections.from()` returns a `ReadOnlyQueryBuilder` (only `find`, `findById`, `count`, `findMetadata`, `findMetadataById`). Write operations (`create`, `update`, `remove`, `updateMany`, `removeMany`) are only available on `server.collections.from()`.
 
 ```typescript
 // List query - returns PayloadFindResponse
-const { docs, totalDocs, hasNextPage } = await client.from('products').find({
+const { docs, totalDocs, hasNextPage } = await client.collections.from('products').find({
   limit: 20,
   page: 1,
   sort: '-createdAt',
@@ -131,57 +137,57 @@ const { docs, totalDocs, hasNextPage } = await client.from('products').find({
 })
 
 // Query with populate/joins control
-const { docs } = await client.from('products').find({
+const { docs } = await client.collections.from('products').find({
   select: { title: true, slug: true, price: true, thumbnail: true },
   joins: false, // disable joins for lightweight list
 })
 
 // Override relationship populate
-const product = await client.from('products').findById(id, {
+const product = await client.collections.from('products').findById(id, {
   populate: { brands: { name: true, logo: true } },
   joins: { variants: { limit: 50 } },
 })
 
 // Single item query - returns document directly
-const product = await client.from('products').findById('id')
+const product = await client.collections.from('products').findById('id')
 
 // Create (server only) - returns PayloadMutationResponse
-const { doc, message } = await client
+const { doc, message } = await server.collections
   .from('products')
   .create({ name: 'Product' })
 
 // Create with file upload (server only) - uses multipart/form-data
-const { doc } = await client
+const { doc } = await server.collections
   .from('images')
   .create({ alt: 'Hero image' }, { file: imageFile, filename: 'hero.jpg' })
 
 // Update (server only) - returns PayloadMutationResponse
-const { doc } = await client.from('products').update('id', { name: 'Updated' })
+const { doc } = await server.collections.from('products').update('id', { name: 'Updated' })
 
 // Update with file replacement (server only)
-await client.from('images').update('id', { alt: 'New alt' }, { file: newFile })
+await server.collections.from('images').update('id', { alt: 'New alt' }, { file: newFile })
 
 // Delete (server only) - returns document directly
-const deletedDoc = await client.from('products').remove('id')
+const deletedDoc = await server.collections.from('products').remove('id')
 
 // Count
-const { totalDocs } = await client.from('products').count()
+const { totalDocs } = await client.collections.from('products').count()
 
 // SEO Metadata (fetch + generate in one call, depth: 1 auto-applied)
-const metadata = await client
+const metadata = await client.collections
   .from('products')
   .findMetadata(
     { where: { slug: { equals: 'my-product' } } },
     { siteName: 'My Store' },
   )
 
-const metadataById = await client.from('products').findMetadataById('id', {
+const metadataById = await client.collections.from('products').findMetadataById('id', {
   siteName: 'My Store',
 })
 
 // Bulk operations (server only)
-await client.from('products').updateMany(where, data)
-await client.from('products').removeMany(where)
+await server.collections.from('products').updateMany(where, data)
+await server.collections.from('products').removeMany(where)
 ```
 
 ### API Response Types (Payload Native)
@@ -303,7 +309,7 @@ client.query.setCustomerData(profile)
 
 ### Customer Auth
 
-Available on Client via `client.customer.*`.
+Available on Client via `client.customer.auth.*`.
 
 ```typescript
 const client = createClient({
@@ -312,83 +318,114 @@ const client = createClient({
 })
 
 // Register & login
-const { customer } = await client.customer.register({
+const { customer } = await client.customer.auth.register({
   name: 'John',
   email: 'john@example.com',
   password: 'secure123',
 })
-const { token, customer } = await client.customer.login({
+const { token, customer } = await client.customer.auth.login({
   email: 'john@example.com',
   password: 'secure123',
 })
 
 // Profile & token management
-const profile = await client.customer.me()
-client.customer.isAuthenticated()
-client.customer.logout()
+const profile = await client.customer.auth.me()
+client.customer.auth.isAuthenticated()
+client.customer.auth.logout()
 
-// Orders
-const orders = await client.customer.getMyOrders({
+// Authenticated customer's own orders (Client-only)
+const orders = await client.commerce.orders.listMine({
   page: 1,
   limit: 10,
   status: 'paid',
 })
 
 // Password & email
-await client.customer.forgotPassword('john@example.com')
-await client.customer.resetPassword(token, newPassword)
-await client.customer.changePassword(currentPassword, newPassword)
-await client.customer.verifyEmail(verificationToken)
+await client.customer.auth.forgotPassword('john@example.com')
+await client.customer.auth.resetPassword(token, newPassword)
+await client.customer.auth.changePassword(currentPassword, newPassword)
+await client.customer.auth.verifyEmail(verificationToken)
 ```
 
-### Server API
+### Commerce Orders (ServerClient-only writes)
 
-Available only in ServerClient via `client.api.*`.
+Available on ServerClient via `server.commerce.orders.*`. Only `checkout` and `listMine` are also on Client.
 
 ```typescript
 // Orders
-await client.api.createOrder(params)
-await client.api.updateOrder({ orderNumber, status })
-await client.api.getOrder({ orderNumber })
-await client.api.checkout({ cartId, paymentId, orderNumber, customerSnapshot, discountCode? })
+await server.commerce.orders.create(params)
+await server.commerce.orders.update({ orderNumber, status })
+await server.commerce.orders.checkout({ cartId, pgPaymentId?, orderNumber, customerSnapshot, discountCode? })
+
+// Single-order lookup (getOrder endpoint removed — use collection find)
+const { docs: [order] } = await server.collections.from('orders').find({
+  where: { orderNumber: { equals: 'ORD-...' } },
+  limit: 1,
+  depth: 1,
+})
 
 // Fulfillment & transactions
-await client.api.createFulfillment({ orderNumber, carrier, trackingNumber, items })
-await client.api.updateTransaction({ paymentId, status, paymentMethod, receiptUrl })
+await server.commerce.orders.createFulfillment({ orderNumber, carrier, trackingNumber, items })
+await server.commerce.orders.bulkImportFulfillments({ items: [{ orderNumber, carrier?, trackingNumber? }] })
+await server.commerce.orders.updateTransaction({ pgPaymentId, status, paymentMethod, receiptUrl })
 
 // Returns
-await client.api.createReturn({ orderNumber, returnProducts, refundAmount, reason? })
-await client.api.updateReturn({ returnId, status })
-await client.api.returnWithRefund({ orderNumber, returnProducts, refundAmount, paymentId })
+await server.commerce.orders.createReturn({ orderNumber, returnItems, refundAmount, reason? })
+await server.commerce.orders.updateReturn({ returnId, status })
+await server.commerce.orders.returnWithRefund({ orderNumber, returnItems, refundAmount, pgPaymentId })
+```
+
+### Commerce Discounts / Shipping
+
+Available on both Client (customer JWT) and ServerClient (secretKey).
+
+```typescript
+await client.commerce.discounts.validate({ code, orderAmount })
+await client.commerce.shipping.calculate({ shippingPolicyId?, orderAmount, postalCode? })
+// calculateShipping returns: { shippingAmount, baseShippingAmount, extraShippingAmount, freeShipping, freeShippingMinAmount, isJeju, isRemoteIsland }
 ```
 
-### Product API
+### Commerce Product
 
-Available only in ServerClient via `client.product.*`.
+Available on both Client and ServerClient via `commerce.product.*`.
 
 ```typescript
-// Batch stock check
-const { results, allAvailable } = await client.product.stockCheck({
+// Batch stock check (point-in-time read, NOT a reservation)
+const { results, allAvailable } = await client.commerce.product.stockCheck({
   items: [
-    { optionId: 1, quantity: 2 },
-    { optionId: 3, quantity: 1 },
+    { variantId: '...', quantity: 2 },
   ],
 })
 ```
 
-### Cart API
+### Commerce Cart
 
-Available in both ServerClient and Client via `client.cart.*`.
+Available on both Client and ServerClient via `commerce.cart.*`.
 
 ```typescript
 // Add item to cart
-await client.cart.addItem({ cartId, product, variant, option, quantity })
+await client.commerce.cart.addItem({ cartId, product, variant, option, quantity })
 
 // Update item quantity
-await client.cart.updateItem({ cartItemId, quantity })
+await client.commerce.cart.updateItem({ cartItemId, quantity })
 
 // Remove item from cart
-await client.cart.removeItem({ cartItemId })
+await client.commerce.cart.removeItem({ cartItemId })
+
+// Other cart operations
+await client.commerce.cart.get(cartId)
+await client.commerce.cart.applyDiscount({ cartId, discountCode })
+await client.commerce.cart.removeDiscount({ cartId })
+await client.commerce.cart.clear({ cartId })
+```
+
+### Community Moderation (ServerClient-only)
+
+Available only on ServerClient via `server.community.moderation.*`.
+
+```typescript
+await server.community.moderation.banCustomer({ customerId, isPermanent?, bannedUntil?, reason? })
+await server.community.moderation.unbanCustomer({ customerId })
 ```
 
 ### Webhook
@@ -520,7 +557,7 @@ The SDK throws typed errors instead of returning error responses:
 import { isNetworkError, isApiError, isValidationError } from '@01.software/sdk'
 
 try {
-  const { docs } = await client.from('products').find()
+  const { docs } = await client.collections.from('products').find()
 } catch (error) {
   if (isNetworkError(error)) {
     console.error('Network issue:', error.message)

package/dist/{const-CRjjFJ3o.d.ts → const-DSTPrI77.d.ts}

@@ -1,4 +1,4 @@
-import { C as Config } from './payload-types-D4IWd3ZB.js';
+import { C as Config } from './payload-types-DqX4iuTW.js';
 
 /**
  * Collection type derived from Payload Config.

package/dist/{const-CZOY2tsf.d.cts → const-DqcpKgSA.d.cts}

@@ -1,4 +1,4 @@
-import { C as Config } from './payload-types-D4IWd3ZB.cjs';
+import { C as Config } from './payload-types-DqX4iuTW.cjs';
 
 /**
  * Collection type derived from Payload Config.