@01.software/sdk 0.8.0 → 0.9.0

package/README.md

@@ -29,12 +29,8 @@ pnpm add @01.software/sdk
 // Main entry - clients, query builder, hooks, utilities
 import { createClient, createServerClient } from '@01.software/sdk'
 
-// Auth only - JWT & API Key utilities (smaller bundle)
-import {
-  createServerToken,
-  verifyServerToken,
-  createApiKey,
-} from '@01.software/sdk/auth'
+// Auth only - customer JWT utilities (smaller bundle)
+import { verifyCustomerToken } from '@01.software/sdk/auth'
 
 // Webhook only - webhook handlers
 import {
@@ -59,7 +55,7 @@ import { VideoPlayer } from '@01.software/sdk/ui/video'
 import { createClient } from '@01.software/sdk'
 
 const client = createClient({
-  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
+  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY,
 })
 
 // Query data (returns Payload native response)
@@ -75,8 +71,8 @@ const { docs } = await client.from('products').find({
 import { createServerClient } from '@01.software/sdk'
 
 const client = createServerClient({
-  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
-  secretKey: process.env.SOFTWARE_SECRET_KEY,
+  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY,
+  secretKey: process.env.SOFTWARE_SECRET_KEY, // sk01_... opaque API key from Console
 })
 
 // Create order (server only)
@@ -103,14 +99,14 @@ await client.query.prefetchQuery({
 
 ```typescript
 const client = createClient({
-  clientKey: string, // Required
+  publishableKey: string, // Required
 })
 ```
 
-| Option      | Type     | Description                  |
-| ----------- | -------- | ---------------------------- |
-| `clientKey` | `string` | API client key               |
-| `secretKey` | `string` | API secret key (server only) |
+| Option           | Type     | Description                  |
+| ---------------- | -------- | ---------------------------- |
+| `publishableKey` | `string` | API publishable key          |
+| `secretKey`      | `string` | API secret key (server only) |
 
 API URL은 환경변수로 오버라이드 가능합니다:
 
@@ -311,7 +307,7 @@ Available on Client via `client.customer.*`.
 
 ```typescript
 const client = createClient({
-  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
+  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY,
   customer: { persist: true },
 })
 
@@ -452,7 +448,7 @@ import { resolveRelation } from '@01.software/sdk'
 const author = resolveRelation(post.author) // Author | null
 ```
 
-> **Note:** `objectFor` is still available but deprecated. Use `resolveRelation` instead.
+> **Note:** Prefer `resolveRelation`. It covers the same normalization use case directly.
 
 ### generateOrderNumber
 
@@ -539,12 +535,14 @@ Error classes: `SDKError`, `ApiError`, `NetworkError`, `ValidationError`, `Confi
 ## Environment Variables
 
 ```bash
-NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=your_client_key
-SOFTWARE_SECRET_KEY=your_secret_key  # Server only
+NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY=your_publishable_key
+SOFTWARE_SECRET_KEY=sk01_...  # Server only — opaque API key from Console
 ```
 
 > `secretKey` should only be used in server environments. Never expose it to the browser.
 
+> **SDK 0.9.0**: Server auth now uses opaque bearer tokens (`sk01_...`). Generate API keys from the Console. `createServerToken`, `createApiKey`, and `parseApiKey` are no longer part of the SDK surface.
+
 ## Migration Guide
 
 ### v0.8.0 (Breaking Changes)

package/dist/{const-dv0zuAxG.d.cts → const-DZ04SC2y.d.cts}

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

package/dist/{const-CCh99Gxu.d.ts → const-hXu9oG66.d.ts}

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

package/dist/index.cjs

@@ -46,13 +46,10 @@ __export(src_exports, {
   UsageLimitError: () => UsageLimitError,
   ValidationError: () => ValidationError,
   collectionKeys: () => collectionKeys,
-  createApiKey: () => createApiKey,
   createClient: () => createClient,
   createServerClient: () => createServerClient,
-  createServerToken: () => createServerToken,
   createTypedWebhookHandler: () => createTypedWebhookHandler,
   customerKeys: () => customerKeys,
-  decodeServerToken: () => decodeServerToken,
   formatOrderName: () => formatOrderName,
   generateOrderNumber: () => generateOrderNumber,
   getImageLqip: () => getImageLqip,
@@ -77,91 +74,10 @@ __export(src_exports, {
   isUsageLimitError: () => isUsageLimitError,
   isValidWebhookEvent: () => isValidWebhookEvent,
   isValidationError: () => isValidationError,
-  parseApiKey: () => parseApiKey,
-  resolveRelation: () => resolveRelation,
-  verifyServerToken: () => verifyServerToken
+  resolveRelation: () => resolveRelation
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/core/internal/utils/jwt.ts
-var import_jose = require("jose");
-async function createServerToken(clientKey, secretKey, expiresIn = "1h") {
-  if (!clientKey || !secretKey) {
-    throw new Error("clientKey and secretKey are required.");
-  }
-  const secret = new TextEncoder().encode(secretKey);
-  return new import_jose.SignJWT({ clientKey }).setProtectedHeader({ alg: "HS256" }).setIssuedAt().setExpirationTime(expiresIn).sign(secret);
-}
-async function verifyServerToken(token, secretKey) {
-  if (!token || !secretKey) {
-    throw new Error("token and secretKey are required.");
-  }
-  const secret = new TextEncoder().encode(secretKey);
-  const { payload } = await (0, import_jose.jwtVerify)(token, secret, {
-    algorithms: ["HS256"]
-  });
-  if (!payload.clientKey || typeof payload.clientKey !== "string") {
-    throw new Error("Invalid token payload: clientKey is missing");
-  }
-  return {
-    clientKey: payload.clientKey,
-    iat: payload.iat,
-    exp: payload.exp
-  };
-}
-function decodeServerToken(token) {
-  if (!token) {
-    throw new Error("token is required.");
-  }
-  const payload = (0, import_jose.decodeJwt)(token);
-  if (!payload.clientKey || typeof payload.clientKey !== "string") {
-    throw new Error("Invalid token payload: clientKey is missing");
-  }
-  return {
-    clientKey: payload.clientKey,
-    iat: payload.iat,
-    exp: payload.exp
-  };
-}
-
-// src/core/internal/utils/encoding.ts
-function createApiKey(clientKey, secretKey) {
-  if (!clientKey || !secretKey) {
-    throw new Error("clientKey and secretKey are required.");
-  }
-  if (typeof Buffer !== "undefined") {
-    return Buffer.from(`${clientKey}:${secretKey}`).toString("base64");
-  }
-  return btoa(`${clientKey}:${secretKey}`);
-}
-function parseApiKey(apiKey) {
-  if (!apiKey) {
-    throw new Error("apiKey is required.");
-  }
-  try {
-    let decoded;
-    if (typeof Buffer !== "undefined") {
-      decoded = Buffer.from(apiKey, "base64").toString("utf-8");
-    } else {
-      decoded = atob(apiKey);
-    }
-    const colonIndex = decoded.indexOf(":");
-    if (colonIndex === -1) {
-      throw new Error("Invalid format: missing colon separator");
-    }
-    const clientKey = decoded.substring(0, colonIndex);
-    const secretKey = decoded.substring(colonIndex + 1);
-    if (!clientKey || !secretKey) {
-      throw new Error("Invalid format: empty clientKey or secretKey");
-    }
-    return { clientKey, secretKey };
-  } catch {
-    throw new Error(
-      'Invalid API key. Expected Base64 encoded "clientKey:secretKey"'
-    );
-  }
-}
-
 // src/core/internal/errors/index.ts
 var SDKError = class extends Error {
   constructor(code, message, status, details, userMessage, suggestion) {
@@ -282,7 +198,6 @@ function isUsageLimitError(error) {
   return error instanceof UsageLimitError;
 }
 var createNetworkError = (message, status, details, userMessage, suggestion) => new NetworkError(message, status, details, userMessage, suggestion);
-var createValidationError = (message, details, userMessage, suggestion) => new ValidationError(message, details, userMessage, suggestion);
 var createApiError = (message, status, details, userMessage, suggestion) => new ApiError(message, status, details, userMessage, suggestion);
 var createConfigError = (message, details, userMessage, suggestion) => new ConfigError(message, details, userMessage, suggestion);
 var createTimeoutError = (message, details, userMessage, suggestion) => new TimeoutError(message, details, userMessage, suggestion);
@@ -376,24 +291,24 @@ async function delay(ms) {
 }
 async function httpFetch(url, options) {
   const {
-    clientKey,
+    publishableKey,
     secretKey,
     customerToken,
     timeout = DEFAULT_TIMEOUT,
-    baseUrl = resolveApiUrl(),
     debug,
     retry,
     onUnauthorized,
     ...requestInit
   } = options || {};
+  const baseUrl = resolveApiUrl();
   const retryConfig = {
     maxRetries: retry?.maxRetries ?? 3,
     retryableStatuses: retry?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES,
     retryDelay: retry?.retryDelay ?? ((attempt) => Math.min(1e3 * 2 ** attempt, 1e4))
   };
   let authToken;
-  if (secretKey && clientKey) {
-    authToken = await createServerToken(clientKey, secretKey);
+  if (secretKey) {
+    authToken = secretKey;
   } else if (customerToken) {
     authToken = customerToken;
   }
@@ -402,8 +317,8 @@ async function httpFetch(url, options) {
   for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
     try {
       const headers = new Headers(requestInit.headers);
-      if (clientKey) {
-        headers.set("X-Client-Key", clientKey);
+      if (publishableKey) {
+        headers.set("X-Publishable-Key", publishableKey);
       }
       if (authToken) {
         headers.set("Authorization", `Bearer ${authToken}`);
@@ -594,23 +509,18 @@ async function parseApiResponse(response, endpoint) {
 // src/core/api/base-api.ts
 var BaseApi = class {
   constructor(apiName, options) {
-    if (!options.clientKey) {
-      throw createConfigError(`clientKey is required for ${apiName}.`);
-    }
     if (!options.secretKey) {
       throw createConfigError(`secretKey is required for ${apiName}.`);
     }
-    this.clientKey = options.clientKey;
+    this.publishableKey = options.publishableKey ?? "";
     this.secretKey = options.secretKey;
-    this.baseUrl = options.baseUrl;
   }
   async request(endpoint, body, options) {
     const method = options?.method ?? "POST";
     const response = await httpFetch(endpoint, {
       method,
-      clientKey: this.clientKey,
+      publishableKey: this.publishableKey,
       secretKey: this.secretKey,
-      baseUrl: this.baseUrl,
       ...body !== void 0 && { body: JSON.stringify(body) },
       ...options?.headers && { headers: options.headers }
     });
@@ -673,28 +583,23 @@ var OrderApi = class extends BaseApi {
 // src/core/api/cart-api.ts
 var CartApi = class {
   constructor(options) {
-    if (!options.clientKey) {
-      throw createConfigError("clientKey is required for CartApi.");
-    }
     if (!options.secretKey && !options.customerToken) {
       throw createConfigError(
         "Either secretKey or customerToken is required for CartApi."
       );
     }
-    this.clientKey = options.clientKey;
+    this.publishableKey = options.publishableKey ?? "";
     this.secretKey = options.secretKey;
     this.customerToken = options.customerToken;
-    this.baseUrl = options.baseUrl;
     this.onUnauthorized = options.onUnauthorized;
   }
   async execute(endpoint, method, body) {
     const token = typeof this.customerToken === "function" ? this.customerToken() : this.customerToken;
     const response = await httpFetch(endpoint, {
       method,
-      clientKey: this.clientKey,
+      publishableKey: this.publishableKey,
       secretKey: this.secretKey,
       customerToken: token ?? void 0,
-      baseUrl: this.baseUrl,
       ...token && this.onUnauthorized && { onUnauthorized: this.onUnauthorized },
       ...body !== void 0 && { body: JSON.stringify(body) }
     });
@@ -941,21 +846,16 @@ var CollectionQueryBuilder = class {
 // src/core/collection/http-client.ts
 var import_qs_esm = require("qs-esm");
 var HttpClient = class {
-  constructor(clientKey, secretKey, baseUrl, getCustomerToken, onUnauthorized) {
-    if (!clientKey) {
-      throw createValidationError("clientKey is required.");
-    }
-    this.clientKey = clientKey;
+  constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized) {
+    this.publishableKey = publishableKey;
     this.secretKey = secretKey;
-    this.baseUrl = baseUrl;
     this.getCustomerToken = getCustomerToken;
     this.onUnauthorized = onUnauthorized;
   }
   get defaultOptions() {
     const opts = {
-      clientKey: this.clientKey,
-      secretKey: this.secretKey,
-      baseUrl: this.baseUrl
+      publishableKey: this.publishableKey,
+      secretKey: this.secretKey
     };
     const token = this.getCustomerToken?.();
     if (token) {
@@ -1070,9 +970,6 @@ function buildPayloadFormData(data, file, filename) {
   return formData;
 }
 var CollectionClient = class extends HttpClient {
-  constructor(clientKey, secretKey, baseUrl, getCustomerToken, onUnauthorized) {
-    super(clientKey, secretKey, baseUrl, getCustomerToken, onUnauthorized);
-  }
   from(collection) {
     return new CollectionQueryBuilder(this, collection);
   }
@@ -1274,23 +1171,18 @@ var COLLECTIONS = [
 // src/core/community/community-client.ts
 var CommunityClient = class {
   constructor(options) {
-    if (!options.clientKey) {
-      throw createConfigError("clientKey is required for CommunityClient.");
-    }
-    this.clientKey = options.clientKey;
+    this.publishableKey = options.publishableKey ?? "";
     this.secretKey = options.secretKey;
     this.customerToken = options.customerToken;
-    this.baseUrl = options.baseUrl;
     this.onUnauthorized = options.onUnauthorized;
   }
   async execute(endpoint, method, body) {
     const token = typeof this.customerToken === "function" ? this.customerToken() : this.customerToken;
     const response = await httpFetch(endpoint, {
       method,
-      clientKey: this.clientKey,
+      publishableKey: this.publishableKey,
       secretKey: this.secretKey,
       customerToken: token ?? void 0,
-      baseUrl: this.baseUrl,
       ...token && this.onUnauthorized && { onUnauthorized: this.onUnauthorized },
       ...body !== void 0 && { body: JSON.stringify(body) }
     });
@@ -1467,10 +1359,10 @@ function safeGetItem(key) {
   }
 }
 var CustomerAuth = class {
-  constructor(clientKey, baseUrl, options) {
+  constructor(publishableKey, options) {
     this.refreshPromise = null;
-    this.clientKey = clientKey;
-    this.baseUrl = baseUrl;
+    this.publishableKey = publishableKey;
+    this.baseUrl = resolveApiUrl();
     const persist = options?.persist ?? true;
     if (persist) {
       const key = typeof persist === "string" ? persist : "customer-token";
@@ -1656,7 +1548,7 @@ var CustomerAuth = class {
    */
   async requestJson(path, init) {
     const headers = new Headers(init.headers);
-    headers.set("X-Client-Key", this.clientKey);
+    headers.set("X-Publishable-Key", this.publishableKey);
     if (!headers.has("Content-Type") && init.body) {
       headers.set("Content-Type", "application/json");
     }
@@ -2136,11 +2028,11 @@ var QueryHooks = class extends CollectionHooks {
 // src/core/client/client.ts
 var Client = class {
   constructor(options) {
-    if (!options.clientKey) {
-      throw createConfigError("clientKey is required.");
+    const publishableKey = options.publishableKey;
+    if (!publishableKey) {
+      throw createConfigError("publishableKey is required.");
     }
-    this.config = { ...options };
-    this.baseUrl = resolveApiUrl();
+    this.config = { ...options, publishableKey };
     const metadata = {
       timestamp: Date.now(),
       userAgent: typeof window !== "undefined" ? window.navigator?.userAgent : "Node.js"
@@ -2148,8 +2040,7 @@ var Client = class {
     this.state = { metadata };
     this.queryClient = getQueryClient();
     this.customer = new CustomerAuth(
-      this.config.clientKey,
-      this.baseUrl,
+      this.config.publishableKey,
       options.customer
     );
     const onUnauthorized = async () => {
@@ -2161,21 +2052,18 @@ var Client = class {
       }
     };
     this.cart = new CartApi({
-      clientKey: this.config.clientKey,
+      publishableKey: this.config.publishableKey,
       customerToken: () => this.customer.getToken(),
-      baseUrl: this.baseUrl,
       onUnauthorized
     });
     this.community = new CommunityClient({
-      clientKey: this.config.clientKey,
+      publishableKey: this.config.publishableKey,
       customerToken: () => this.customer.getToken(),
-      baseUrl: this.baseUrl,
       onUnauthorized
     });
     this.collections = new CollectionClient(
-      this.config.clientKey,
+      this.config.publishableKey,
       void 0,
-      this.baseUrl,
       () => this.customer.getToken(),
       onUnauthorized
     );
@@ -2207,43 +2095,39 @@ var ServerClient = class {
         "ServerClient must not be used in a browser environment. This risks exposing your secretKey in client bundles. Use createClient() for browser code instead."
       );
     }
-    if (!options.clientKey) {
-      throw createConfigError("clientKey is required.");
-    }
     if (!options.secretKey) {
       throw createConfigError("secretKey is required.");
     }
-    this.config = { ...options };
-    this.baseUrl = resolveApiUrl();
+    if (!options.publishableKey) {
+      throw createConfigError(
+        "publishableKey is required. It is used for rate limiting and monthly quota enforcement via the X-Publishable-Key header. Get it from Console > Settings > API Keys."
+      );
+    }
+    this.config = { ...options, publishableKey: options.publishableKey };
     const metadata = {
       timestamp: Date.now(),
       userAgent: "Node.js"
     };
     this.state = { metadata };
     this.api = new OrderApi({
-      clientKey: this.config.clientKey,
-      secretKey: this.config.secretKey,
-      baseUrl: this.baseUrl
+      publishableKey: this.config.publishableKey,
+      secretKey: this.config.secretKey
     });
     this.cart = new CartApi({
-      clientKey: this.config.clientKey,
-      secretKey: this.config.secretKey,
-      baseUrl: this.baseUrl
+      publishableKey: this.config.publishableKey,
+      secretKey: this.config.secretKey
     });
     this.community = new CommunityClient({
-      clientKey: this.config.clientKey,
-      secretKey: this.config.secretKey,
-      baseUrl: this.baseUrl
+      publishableKey: this.config.publishableKey,
+      secretKey: this.config.secretKey
     });
     this.product = new ProductApi({
-      clientKey: this.config.clientKey,
-      secretKey: this.config.secretKey,
-      baseUrl: this.baseUrl
+      publishableKey: this.config.publishableKey,
+      secretKey: this.config.secretKey
     });
     this.collections = new CollectionClient(
-      this.config.clientKey,
-      this.config.secretKey,
-      this.baseUrl
+      this.config.publishableKey,
+      this.config.secretKey
     );
     this.queryClient = getQueryClient();
     this.query = new QueryHooks(this.queryClient, this.collections);
@@ -2269,9 +2153,9 @@ var MAX_RECONNECT_DELAY = 3e4;
 var RECONNECT_BACKOFF_FACTOR = 2;
 var MAX_NO_TOKEN_RETRIES = 5;
 var RealtimeConnection = class {
-  constructor(baseUrl, clientKey, getToken, collections) {
+  constructor(baseUrl, publishableKey, getToken, collections) {
     this.baseUrl = baseUrl;
-    this.clientKey = clientKey;
+    this.publishableKey = publishableKey;
     this.getToken = getToken;
     this.collections = collections;
     this.abortController = null;
@@ -2324,7 +2208,7 @@ var RealtimeConnection = class {
     try {
       const response = await fetch(url, {
         headers: {
-          "X-Client-Key": this.clientKey,
+          "X-Publishable-Key": this.publishableKey,
           Authorization: `Bearer ${token}`
         },
         signal