@01.software/sdk 0.1.0-dev.260211.a92d27b → 0.1.2

package/README.md

@@ -14,9 +14,28 @@ pnpm add @01.software/sdk
 
 - Full TypeScript type inference
 - Browser and server environment support
-- React Query integration
-- Automatic retry with exponential backoff
-- Webhook handling
+- React Query integration (both BrowserClient and ServerClient)
+- Mutation hooks (useCreate, useUpdate, useRemove) with automatic cache invalidation
+- Automatic retry with exponential backoff (non-retryable: 401, 403, 404, 422)
+- Webhook handling with HMAC-SHA256 signature verification
+- Sub-path imports (`./auth`, `./webhook`, `./components`) for tree-shaking
+- Type-safe read-only `from()` for BrowserClient (compile-time write prevention)
+
+### Sub-path Imports
+
+```typescript
+// Main entry - clients, query builder, hooks, utilities
+import { createBrowserClient, createServerClient } from '@01.software/sdk'
+
+// Auth only - JWT & API Key utilities (smaller bundle)
+import { createServerToken, verifyServerToken, createApiKey } from '@01.software/sdk/auth'
+
+// Webhook only - webhook handlers
+import { handleWebhook, createTypedWebhookHandler } from '@01.software/sdk/webhook'
+
+// Components only - React components
+import { RichTextContent } from '@01.software/sdk/components'
+```
 
 ## Getting Started
 
@@ -29,8 +48,8 @@ const client = createBrowserClient({
   clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
 })
 
-// Query data
-const { data } = await client.from('products').find({
+// Query data (returns Payload native response)
+const { docs } = await client.from('products').find({
   limit: 10,
   where: { status: { equals: 'published' } },
 })
@@ -54,6 +73,12 @@ const order = await client.api.createOrder({
   orderProducts: [...],
   totalAmount: 10000,
 })
+
+// SSR prefetch (server)
+await client.query.prefetchQuery({
+  collection: 'products',
+  options: { limit: 10 },
+})
 ```
 
 ## API
@@ -63,84 +88,97 @@ const order = await client.api.createOrder({
 ```typescript
 const client = createBrowserClient({
   clientKey: string,           // Required
-  baseUrl?: string,            // API URL (optional)
-  debug?: boolean | DebugOptions,
-  retry?: RetryOptions,
-  errorLogger?: ErrorLogger,
+  environment?: Environment,   // 'local' | 'development' | 'staging' | 'production'
+  baseUrl?: string,            // Custom API URL (overrides environment)
 })
 ```
 
-| Option      | Type                      | Description                  |
-| ----------- | ------------------------- | ---------------------------- |
-| `clientKey` | `string`                  | API client key               |
-| `secretKey` | `string`                  | API secret key (server only) |
-| `baseUrl`   | `string`                  | API base URL                 |
-| `debug`     | `boolean \| DebugOptions` | Enable debug logging         |
-| `retry`     | `RetryOptions`            | Retry configuration          |
+| Option        | Type          | Description                  |
+| ------------- | ------------- | ---------------------------- |
+| `clientKey`   | `string`      | API client key               |
+| `secretKey`   | `string`      | API secret key (server only) |
+| `environment` | `Environment` | API environment              |
+| `baseUrl`     | `string`      | Custom API URL               |
 
 ### Query Builder
 
 Access collections via `client.from(collection)` method.
 
+> **Note:** `BrowserClient.from()` returns a `ReadOnlyQueryBuilder` (only `find`, `findById`, `count`). Write operations (`create`, `update`, `remove`, `updateMany`, `removeMany`) are only available on `ServerClient.from()`.
+
 ```typescript
-// List query
-const { data } = await client.from('products').find({
+// List query - returns PayloadFindResponse
+const { docs, totalDocs, hasNextPage } = await client.from('products').find({
   limit: 20,
   page: 1,
   sort: '-createdAt',
   where: { status: { equals: 'published' } },
+  depth: 2,
+  select: { title: true, slug: true },
 })
 
-// Single item query
-const { data } = await client.from('products').findById('id')
+// Single item query - returns document directly
+const product = await client.from('products').findById('id')
+
+// Create (server only) - returns PayloadMutationResponse
+const { doc, message } = await client.from('products').create({ name: 'Product' })
 
-// Create (server only)
-const { data } = await client.from('products').create({ name: 'Product' })
+// Update (server only) - returns PayloadMutationResponse
+const { doc } = await client.from('products').update('id', { name: 'Updated' })
 
-// Update (server only)
-const { data } = await client.from('products').update('id', { name: 'Updated' })
+// Delete (server only) - returns document directly
+const deletedDoc = await client.from('products').remove('id')
 
-// Delete (server only)
-await client.from('products').remove('id')
+// Count
+const { totalDocs } = await client.from('products').count()
+
+// Bulk operations (server only)
+await client.from('products').updateMany(where, data)
+await client.from('products').removeMany(where)
 ```
 
-### API Response Structure
+### API Response Types (Payload Native)
 
-All SDK methods return a standardized response format:
+The SDK returns Payload CMS native response types without wrapping:
 
 ```typescript
-// Success Response
-interface ApiSuccessResponse<T> {
-  data: T                    // Actual data
-  success: true
-  message?: string           // Optional message from server
-  pagination?: PaginationMeta // For list queries
+// find() returns PayloadFindResponse<T>
+interface PayloadFindResponse<T> {
+  docs: T[]
+  totalDocs: number
+  limit: number
+  totalPages: number
+  page: number
+  pagingCounter: number
+  hasPrevPage: boolean
+  hasNextPage: boolean
+  prevPage: number | null
+  nextPage: number | null
 }
 
-// Error Response
-interface ApiErrorResponse {
-  data: null
-  success: false
-  error: {
-    code: string
-    message: string
-    details?: unknown
-  }
+// create() / update() returns PayloadMutationResponse<T>
+interface PayloadMutationResponse<T> {
+  message: string
+  doc: T
+  errors?: unknown[]
 }
-```
 
-**Payload CMS API Mapping:**
+// findById() / remove() returns T (document directly)
+```
 
-| Operation | Payload Response | SDK Response |
-|-----------|-----------------|--------------|
-| `find()` | `{docs: [], totalDocs, ...}` | `{data: [], success: true, pagination: {...}}` |
-| `findById()` | `{...document}` | `{data: {...}, success: true}` |
-| `create()` | `{doc: {...}, message}` | `{data: {...}, success: true, message}` |
-| `update()` | `{doc: {...}, message}` | `{data: {...}, success: true, message}` |
-| `remove()` | `{doc: {...}, message}` | `{data: {...}, success: true, message}` |
+| Operation | Response Type |
+|-----------|--------------|
+| `find()` | `PayloadFindResponse<T>` - `{ docs, totalDocs, hasNextPage, ... }` |
+| `findById()` | `T` - document object directly |
+| `create()` | `PayloadMutationResponse<T>` - `{ doc, message }` |
+| `update()` | `PayloadMutationResponse<T>` - `{ doc, message }` |
+| `remove()` | `T` - deleted document object directly |
+| `count()` | `{ totalDocs: number }` |
 
 ### React Query Hooks
 
+Available on both `BrowserClient` and `ServerClient` via `client.query.*`.
+
 ```typescript
 // List query
 const { data, isLoading } = client.query.useQuery({
@@ -165,21 +203,40 @@ const { data, fetchNextPage, hasNextPage } = client.query.useInfiniteQuery({
   collection: 'products',
   options: { limit: 20 },
 })
+
+// Mutation hooks (auto-invalidate cache on success)
+const { mutate: create } = client.query.useCreate({ collection: 'products' })
+const { mutate: update } = client.query.useUpdate({ collection: 'products' })
+const { mutate: remove } = client.query.useRemove({ collection: 'products' })
+
+create({ title: 'New Product' })
+update({ id: 'product_id', data: { title: 'Updated' } })
+remove('product_id')
+
+// SSR Prefetch
+await client.query.prefetchQuery({ collection: 'products', options: { limit: 10 } })
+await client.query.prefetchQueryById({ collection: 'products', id: 'product_id' })
+await client.query.prefetchInfiniteQuery({ collection: 'products', pageSize: 20 })
+
+// Cache utilities
+client.query.invalidateQueries('products')
+client.query.getQueryData('products', 'list', options)
+client.query.setQueryData('products', 'detail', id, data)
 ```
 
 ### Server API
 
-Available only in ServerClient.
+Available only in ServerClient via `client.api.*`.
 
 ```typescript
 // Create order
-await client.api.createOrder(data)
+await client.api.createOrder(params)
 
-// Update order
-await client.api.updateOrder(id, data)
+// Update order status
+await client.api.updateOrder({ orderNumber, status })
 
 // Update transaction
-await client.api.updateTransaction(id, data)
+await client.api.updateTransaction({ paymentId, status, paymentMethod, receiptUrl })
 ```
 
 ### Webhook
@@ -194,6 +251,13 @@ export async function POST(request: Request) {
   })
 }
 
+// With signature verification
+export async function POST(request: Request) {
+  return handleWebhook(request, handler, {
+    secret: process.env.WEBHOOK_SECRET,
+  })
+}
+
 // Type-safe handler
 const handler = createTypedWebhookHandler('orders', async (event) => {
   // event.data is typed as Order
@@ -210,9 +274,22 @@ const handler = createTypedWebhookHandler('orders', async (event) => {
 | Orders   | `orders`, `order-products`, `returns`, `return-products`, `transactions`                                                           |
 | Content  | `posts`, `post-categories`, `post-tags`, `post-images`, `documents`, `document-categories`, `document-images`                      |
 | Media    | `playlists`, `playlist-images`, `musics`, `galleries`, `gallery-images`, `media`                                                   |
+| Forms    | `forms`, `form-submissions`                                                                                                        |
 
 ## Utilities
 
+### resolveRelation
+
+Resolves a Payload CMS relation field value. When `depth` is 0, relation fields return just an ID (number). When `depth > 0`, they return the full object. This utility normalizes both cases.
+
+```typescript
+import { resolveRelation } from '@01.software/sdk'
+
+const author = resolveRelation(post.author) // Author | null
+```
+
+> **Note:** `objectFor` is still available but deprecated. Use `resolveRelation` instead.
+
 ### generateOrderNumber
 
 ```typescript
@@ -227,14 +304,14 @@ const orderNumber = generateOrderNumber()
 ```typescript
 import { formatOrderName } from '@01.software/sdk'
 
-formatOrderName([{ product: { name: 'Product A' } }])
+formatOrderName([{ product: { title: 'Product A' } }])
 // "Product A"
 
 formatOrderName([
-  { product: { name: 'Product A' } },
-  { product: { name: 'Product B' } },
+  { product: { title: 'Product A' } },
+  { product: { title: 'Product B' } },
 ])
-// "Product A and 1 more"
+// "Product A 외 1건"
 ```
 
 ### RichTextContent
@@ -257,23 +334,23 @@ import { RichTextContent } from '@01.software/sdk'
 
 ## Error Handling
 
+The SDK throws typed errors instead of returning error responses:
+
 ```typescript
-import {
-  isNetworkError,
-  isSuccessResponse,
-  isErrorResponse,
-} from '@01.software/sdk'
-
-const response = await client.from('products').find()
-
-if (isSuccessResponse(response)) {
-  console.log(response.data)
-} else if (isErrorResponse(response)) {
-  console.error(response.error.message)
+import { isNetworkError, isApiError, isValidationError } from '@01.software/sdk'
+
+try {
+  const { docs } = await client.from('products').find()
+} catch (error) {
+  if (isNetworkError(error)) {
+    console.error('Network issue:', error.message)
+  } else if (isApiError(error)) {
+    console.error('API error:', error.status, error.message)
+  }
 }
 ```
 
-Error classes: `SDKError`, `ApiError`, `NetworkError`, `ValidationError`, `TimeoutError`
+Error classes: `SDKError`, `ApiError`, `NetworkError`, `ValidationError`, `ConfigError`, `TimeoutError`
 
 ## Environment Variables
 

package/dist/auth-AVOXtnYN.d.cts

@@ -0,0 +1,267 @@
+import { Sort, Where } from 'payload';
+import './payload-types-DFzDtXGO.cjs';
+
+declare class SDKError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly details?: unknown;
+    readonly userMessage?: string;
+    readonly suggestion?: string;
+    constructor(code: string, message: string, status?: number, details?: unknown, userMessage?: string, suggestion?: string);
+    getUserMessage(): string;
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        status: number | undefined;
+        details: unknown;
+        userMessage: string | undefined;
+        suggestion: string | undefined;
+    };
+}
+declare class NetworkError extends SDKError {
+    constructor(message: string, status?: number, details?: unknown, userMessage?: string, suggestion?: string);
+}
+declare class ValidationError extends SDKError {
+    constructor(message: string, details?: unknown, userMessage?: string, suggestion?: string);
+}
+declare class ApiError extends SDKError {
+    constructor(message: string, status: number, details?: unknown, userMessage?: string, suggestion?: string);
+}
+declare class ConfigError extends SDKError {
+    constructor(message: string, details?: unknown, userMessage?: string, suggestion?: string);
+}
+declare class TimeoutError extends SDKError {
+    constructor(message?: string, details?: unknown, userMessage?: string, suggestion?: string);
+}
+declare class UsageLimitError extends SDKError {
+    readonly usage: {
+        limit: number;
+        current: number;
+        remaining: number;
+    };
+    constructor(message: string, usage: {
+        limit: number;
+        current: number;
+        remaining: number;
+    }, details?: unknown, userMessage?: string, suggestion?: string);
+    toJSON(): {
+        usage: {
+            limit: number;
+            current: number;
+            remaining: number;
+        };
+        name: string;
+        code: string;
+        message: string;
+        status: number | undefined;
+        details: unknown;
+        userMessage: string | undefined;
+        suggestion: string | undefined;
+    };
+}
+declare function isSDKError(error: unknown): error is SDKError;
+declare function isNetworkError(error: unknown): error is NetworkError;
+declare function isValidationError(error: unknown): error is ValidationError;
+declare function isApiError(error: unknown): error is ApiError;
+declare function isConfigError(error: unknown): error is ConfigError;
+declare function isTimeoutError(error: unknown): error is TimeoutError;
+declare function isUsageLimitError(error: unknown): error is UsageLimitError;
+
+type Environment = 'local' | 'development' | 'staging' | 'production';
+declare const API_URLS: Record<Environment, string>;
+/**
+ * 환경에 맞는 API URL을 반환합니다.
+ * 우선순위: baseUrl > environment > 환경변수 > 기본값(production)
+ */
+declare function resolveApiUrl(config?: {
+    baseUrl?: string;
+    environment?: Environment;
+}): string;
+interface ClientBrowserConfig {
+    clientKey: string;
+    /**
+     * API 환경 설정.
+     * - 'local': localhost:3000
+     * - 'development': dev.01.software
+     * - 'staging': stg.01.software
+     * - 'production': api.01.software
+     *
+     * baseUrl이 설정되면 이 값은 무시됩니다.
+     * @default 'production'
+     */
+    environment?: Environment;
+    /**
+     * 커스텀 API URL. 설정 시 environment 값은 무시됩니다.
+     * @example 'https://my-custom-api.example.com'
+     */
+    baseUrl?: string;
+}
+interface ClientServerConfig extends ClientBrowserConfig {
+    secretKey: string;
+}
+interface ClientMetadata {
+    userAgent?: string;
+    timestamp: number;
+}
+interface ClientState {
+    metadata: ClientMetadata;
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    totalDocs: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    pagingCounter: number;
+    prevPage: number | null;
+    nextPage: number | null;
+}
+/**
+ * Payload CMS Find (List) Response
+ * GET /api/{collection}
+ */
+interface PayloadFindResponse<T = unknown> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    totalPages: number;
+    page: number;
+    pagingCounter: number;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    prevPage: number | null;
+    nextPage: number | null;
+}
+/**
+ * Payload CMS Create/Update Response
+ * POST /api/{collection}
+ * PATCH /api/{collection}/{id}
+ */
+interface PayloadMutationResponse<T = unknown> {
+    message: string;
+    doc: T;
+    errors?: unknown[];
+}
+interface ApiQueryOptions {
+    page?: number;
+    limit?: number;
+    sort?: Sort;
+    where?: Where;
+    depth?: number;
+    select?: Record<string, boolean>;
+}
+interface ApiQueryReactOptions {
+    keepPreviousData?: boolean;
+}
+interface DebugConfig {
+    logRequests?: boolean;
+    logResponses?: boolean;
+    logErrors?: boolean;
+}
+interface RetryConfig {
+    maxRetries?: number;
+    retryableStatuses?: number[];
+    retryDelay?: (attempt: number) => number;
+}
+interface ErrorLogger {
+    log(error: SDKError | Error, context?: Record<string, unknown>): void;
+}
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+type ExtractArrayType<T> = T extends (infer U)[] ? U : never;
+
+interface FetchOptions extends RequestInit {
+    clientKey?: string;
+    secretKey?: string;
+    timeout?: number;
+    baseUrl?: string;
+    debug?: boolean | DebugConfig;
+    retry?: RetryConfig;
+}
+interface JwtPayload {
+    clientKey: string;
+    iat?: number;
+    exp?: number;
+}
+/**
+ * Creates a JWT token for server-side authentication.
+ * The token is valid for 1 hour by default.
+ *
+ * @param clientKey - Client API key
+ * @param secretKey - Secret key used for signing
+ * @param expiresIn - Token expiration time (default: '1h')
+ * @returns Promise<string> JWT token
+ *
+ * @example
+ * ```typescript
+ * const token = await createServerToken('client-key', 'secret-key')
+ * // Use in Authorization header: `Bearer ${token}`
+ * ```
+ */
+declare function createServerToken(clientKey: string, secretKey: string, expiresIn?: string): Promise<string>;
+/**
+ * Verifies a JWT token and returns the payload.
+ *
+ * @param token - JWT token to verify
+ * @param secretKey - Secret key used for verification
+ * @returns Promise<JwtPayload> Verified payload containing clientKey
+ * @throws Error if token is invalid or expired
+ *
+ * @example
+ * ```typescript
+ * const payload = await verifyServerToken(token, 'secret-key')
+ * console.log(payload.clientKey)
+ * ```
+ */
+declare function verifyServerToken(token: string, secretKey: string): Promise<JwtPayload>;
+/**
+ * Decodes a JWT token without verification.
+ * WARNING: Use this only when you need to inspect token contents.
+ * Always use verifyServerToken for authentication.
+ *
+ * @param token - JWT token to decode
+ * @returns JwtPayload Decoded payload (unverified)
+ *
+ * @example
+ * ```typescript
+ * const payload = decodeServerToken(token)
+ * console.log(payload.clientKey) // Unverified!
+ * ```
+ */
+declare function decodeServerToken(token: string): JwtPayload;
+/**
+ * Creates a Base64-encoded API key from clientKey and secretKey.
+ * Use this for MCP server authentication.
+ *
+ * @param clientKey - Client API key
+ * @param secretKey - Secret key
+ * @returns Base64-encoded API key
+ *
+ * @example
+ * ```typescript
+ * const apiKey = createApiKey('client-key', 'secret-key')
+ * // Use in x-api-key header
+ * ```
+ */
+declare function createApiKey(clientKey: string, secretKey: string): string;
+/**
+ * Parses a Base64-encoded API key to extract clientKey and secretKey.
+ *
+ * @param apiKey - Base64-encoded API key
+ * @returns Object containing clientKey and secretKey
+ * @throws Error if API key is invalid
+ *
+ * @example
+ * ```typescript
+ * const { clientKey, secretKey } = parseApiKey(apiKey)
+ * ```
+ */
+declare function parseApiKey(apiKey: string): {
+    clientKey: string;
+    secretKey: string;
+};
+
+export { type ApiQueryOptions as A, type ClientBrowserConfig as C, type DeepPartial as D, type ExtractArrayType as E, type FetchOptions as F, type JwtPayload as J, NetworkError as N, type PayloadFindResponse as P, type RetryConfig as R, SDKError as S, TimeoutError as T, UsageLimitError as U, ValidationError as V, type PayloadMutationResponse as a, type ClientState as b, type ClientServerConfig as c, type DebugConfig as d, type ErrorLogger as e, ApiError as f, ConfigError as g, isNetworkError as h, isSDKError as i, isValidationError as j, isApiError as k, isConfigError as l, isTimeoutError as m, isUsageLimitError as n, createServerToken as o, decodeServerToken as p, createApiKey as q, parseApiKey as r, type Environment as s, API_URLS as t, resolveApiUrl as u, verifyServerToken as v, type ClientMetadata as w, type PaginationMeta as x, type ApiQueryReactOptions as y };