@01.software/sdk 0.20.0 → 0.22.0

package/README.md

@@ -18,9 +18,9 @@ pnpm add @01.software/sdk
 - React Query integration (both Client and ServerClient)
 - Mutation hooks (useCreate, useUpdate, useRemove) with automatic cache invalidation
 - Customer auth hooks (useCustomerMe, useCustomerLogin, etc.) with cache management
-- Automatic retry with exponential backoff (non-retryable: 401, 403, 404, 422)
+- Automatic retry with exponential backoff (non-retryable: 400, 401, 403, 404, 409, 422)
 - Webhook handling with HMAC-SHA256 signature verification
-- Sub-path imports (`./webhook`, `./realtime`, `./ui/*`) for tree-shaking
+- Sub-path imports (`./server`, `./webhook`, `./realtime`, `./ui/*`) for tree-shaking
 - Type-safe read-only `collections.from()` for Client (compile-time write prevention)
 
 ### Sub-path Imports
@@ -37,6 +37,9 @@ analytics.track('signup', { plan: 'pro', trial: false }) // custom event with op
 // Main entry - clients, query builder, hooks, utilities
 import { createClient, createServerClient } from '@01.software/sdk'
 
+// Server-only entry - avoids importing browser Client APIs
+import { createServerClient as createServerOnlyClient } from '@01.software/sdk/server'
+
 // Webhook only - webhook handlers
 import {
   handleWebhook,
@@ -78,7 +81,7 @@ const { docs } = await client.collections.from('products').find({
 ```typescript
 import { createServerClient } from '@01.software/sdk'
 
-const client = createServerClient({
+const server = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY,
   secretKey: process.env.SOFTWARE_SECRET_KEY, // sk01_... opaque API key from Console
 })

package/dist/{const-BApEF1Hu.d.cts → const-CfcjPbOu.d.ts}

@@ -1,4 +1,4 @@
-import { C as Config } from './payload-types-D7lnu9By.cjs';
+import { b as Config } from './payload-types-DeLBmtzd.js';
 
 /**
  * Collection type derived from Payload Config.
@@ -9,7 +9,7 @@ type Collection = keyof Config['collections'];
  * Internal collections that should not be exposed via SDK.
  * Includes Payload system collections and admin-only collections.
  */
-declare const INTERNAL_COLLECTIONS: readonly ["users", "payload-kv", "payload-locked-documents", "payload-preferences", "payload-migrations", "field-configs", "system-media", "track-assets", "audiences", "email-logs", "api-usage", "tenant-analytics-daily", "analytics-event-schemas", "subscriptions", "billing-history", "order-status-logs", "api-keys", "personal-access-tokens", "tenant-entitlements", "webhook-events", "webhook-deliveries", "audit-logs", "plans", "webhooks", "event-registrations"];
+declare const INTERNAL_COLLECTIONS: readonly ["users", "payload-kv", "payload-locked-documents", "payload-preferences", "payload-migrations", "field-configs", "system-media", "track-assets", "audiences", "email-logs", "api-usage", "tenant-analytics-daily", "analytics-event-schemas", "subscriptions", "billing-history", "order-status-logs", "api-keys", "personal-access-tokens", "tenant-entitlements", "direct-upload-sessions", "webhook-events", "webhook-deliveries", "audit-logs", "plans", "webhooks", "event-registrations"];
 /**
  * Array of all public collection names for runtime use (e.g., Zod enum validation).
  * This is the single source of truth for which collections are publicly accessible via SDK.

package/dist/{const-BNJRuk3V.d.ts → const-DraU44bA.d.cts}

@@ -1,4 +1,4 @@
-import { C as Config } from './payload-types-D7lnu9By.js';
+import { b as Config } from './payload-types-DeLBmtzd.cjs';
 
 /**
  * Collection type derived from Payload Config.
@@ -9,7 +9,7 @@ type Collection = keyof Config['collections'];
  * Internal collections that should not be exposed via SDK.
  * Includes Payload system collections and admin-only collections.
  */
-declare const INTERNAL_COLLECTIONS: readonly ["users", "payload-kv", "payload-locked-documents", "payload-preferences", "payload-migrations", "field-configs", "system-media", "track-assets", "audiences", "email-logs", "api-usage", "tenant-analytics-daily", "analytics-event-schemas", "subscriptions", "billing-history", "order-status-logs", "api-keys", "personal-access-tokens", "tenant-entitlements", "webhook-events", "webhook-deliveries", "audit-logs", "plans", "webhooks", "event-registrations"];
+declare const INTERNAL_COLLECTIONS: readonly ["users", "payload-kv", "payload-locked-documents", "payload-preferences", "payload-migrations", "field-configs", "system-media", "track-assets", "audiences", "email-logs", "api-usage", "tenant-analytics-daily", "analytics-event-schemas", "subscriptions", "billing-history", "order-status-logs", "api-keys", "personal-access-tokens", "tenant-entitlements", "direct-upload-sessions", "webhook-events", "webhook-deliveries", "audit-logs", "plans", "webhooks", "event-registrations"];
 /**
  * Array of all public collection names for runtime use (e.g., Zod enum validation).
  * This is the single source of truth for which collections are publicly accessible via SDK.

package/dist/index.cjs

@@ -49,6 +49,7 @@ __export(src_exports, {
   ProductApi: () => ProductApi,
   QueryHooks: () => QueryHooks,
   RateLimitError: () => RateLimitError,
+  ReadOnlyCollectionClient: () => ReadOnlyCollectionClient,
   RealtimeConnection: () => RealtimeConnection,
   SDKError: () => SDKError,
   ServerClient: () => ServerClient,
@@ -177,6 +178,46 @@ function resolveMetaImage(ref) {
 }
 
 // src/core/collection/query-builder.ts
+var ReadOnlyCollectionQueryBuilder = class {
+  constructor(api, collection) {
+    this.api = api;
+    this.collection = collection;
+  }
+  async find(options) {
+    return this.api.requestFind(
+      `/api/${String(this.collection)}`,
+      options
+    );
+  }
+  async findById(id, options) {
+    return this.api.requestFindById(
+      `/api/${String(this.collection)}/${String(id)}`,
+      options
+    );
+  }
+  async count(options) {
+    return this.api.requestCount(
+      `/api/${String(this.collection)}/count`,
+      options
+    );
+  }
+  async findMetadata(options, metadataOptions) {
+    const { docs } = await this.find({ ...options, limit: 1, depth: 1 });
+    const doc = docs[0];
+    if (!doc) return null;
+    return generateMetadata(
+      extractSeo(doc),
+      metadataOptions
+    );
+  }
+  async findMetadataById(id, metadataOptions) {
+    const doc = await this.findById(id, { depth: 1 });
+    return generateMetadata(
+      extractSeo(doc),
+      metadataOptions
+    );
+  }
+};
 var CollectionQueryBuilder = class {
   constructor(api, collection) {
     this.api = api;
@@ -350,8 +391,8 @@ var NetworkError = class extends SDKError {
   }
 };
 var ValidationError = class extends SDKError {
-  constructor(message, details, userMessage, suggestion) {
-    super("VALIDATION_ERROR", message, 400, details, userMessage, suggestion);
+  constructor(message, details, userMessage, suggestion, status = 400) {
+    super("VALIDATION_ERROR", message, status, details, userMessage, suggestion);
     this.name = "ValidationError";
   }
 };
@@ -480,7 +521,7 @@ function isRateLimitError(error) {
   return error instanceof RateLimitError;
 }
 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 createValidationError = (message, details, userMessage, suggestion, status) => new ValidationError(message, details, userMessage, suggestion, status);
 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);
@@ -491,6 +532,16 @@ var createNotFoundError = (message, details, userMessage, suggestion, requestId)
 var createConflictError = (message, details, userMessage, suggestion, requestId) => new ConflictError(message, details, userMessage, suggestion, requestId);
 var createRateLimitError = (message, retryAfter, details, userMessage, suggestion, requestId) => new RateLimitError(message, retryAfter, details, userMessage, suggestion, requestId);
 
+// src/core/internal/utils/credentials.ts
+function requirePublishableKeyForSecret(apiName, publishableKey, secretKey) {
+  if (secretKey && !publishableKey) {
+    throw createConfigError(
+      `publishableKey is required for ${apiName} when secretKey is used. It is sent as X-Publishable-Key for tenant routing, rate limiting, and quota enforcement.`
+    );
+  }
+  return publishableKey ?? "";
+}
+
 // src/core/client/types.ts
 function resolveApiUrl() {
   if (typeof process !== "undefined" && process.env) {
@@ -505,7 +556,7 @@ function resolveApiUrl() {
 // src/core/internal/utils/http.ts
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
-var NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 422];
+var NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 409, 422];
 var SAFE_METHODS = ["GET", "HEAD", "OPTIONS"];
 function debugLog(debug, type, message, data) {
   if (!debug) return;
@@ -588,6 +639,80 @@ function attachRequestId(err, id) {
   if (id) err.requestId = id;
   return err;
 }
+function createHttpStatusError(status, parsed, details, requestId) {
+  const errorDetails = {
+    ...details,
+    ...parsed.errors && { errors: parsed.errors },
+    ...parsed.body && { body: parsed.body }
+  };
+  const suggestion = getErrorSuggestion(status);
+  if (status === 400 || status === 422) {
+    return attachRequestId(
+      createValidationError(
+        parsed.errorMessage,
+        errorDetails,
+        parsed.userMessage,
+        suggestion,
+        status
+      ),
+      requestId
+    );
+  }
+  if (status === 401) {
+    return attachRequestId(
+      createAuthError(
+        parsed.errorMessage,
+        errorDetails,
+        parsed.userMessage,
+        suggestion
+      ),
+      requestId
+    );
+  }
+  if (status === 403) {
+    return attachRequestId(
+      createPermissionError(
+        parsed.errorMessage,
+        errorDetails,
+        parsed.userMessage,
+        suggestion
+      ),
+      requestId
+    );
+  }
+  if (status === 404) {
+    return attachRequestId(
+      createNotFoundError(
+        parsed.errorMessage,
+        errorDetails,
+        parsed.userMessage,
+        suggestion
+      ),
+      requestId
+    );
+  }
+  if (status === 409) {
+    return attachRequestId(
+      createConflictError(
+        parsed.errorMessage,
+        errorDetails,
+        parsed.userMessage,
+        suggestion
+      ),
+      requestId
+    );
+  }
+  return attachRequestId(
+    createNetworkError(
+      parsed.errorMessage,
+      status,
+      errorDetails,
+      parsed.userMessage,
+      suggestion
+    ),
+    requestId
+  );
+}
 async function httpFetch(url, options) {
   const {
     publishableKey,
@@ -692,14 +817,10 @@ async function httpFetch(url, options) {
           attempt: attempt + 1
         };
         if (NON_RETRYABLE_STATUSES.includes(response.status)) {
-          throw attachRequestId(
-            createNetworkError(
-              parsed.errorMessage,
-              response.status,
-              { ...details, ...parsed.errors && { errors: parsed.errors } },
-              parsed.userMessage,
-              getErrorSuggestion(response.status)
-            ),
+          throw createHttpStatusError(
+            response.status,
+            parsed,
+            details,
             requestId
           );
         }
@@ -789,7 +910,11 @@ async function httpFetch(url, options) {
 // src/core/collection/http-client.ts
 var HttpClient = class {
   constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId) {
-    this.publishableKey = publishableKey;
+    this.publishableKey = requirePublishableKeyForSecret(
+      "CollectionClient",
+      publishableKey,
+      secretKey
+    );
     this.secretKey = secretKey;
     this.getCustomerToken = getCustomerToken;
     this.onUnauthorized = onUnauthorized;
@@ -1062,6 +1187,35 @@ var CollectionClient = class extends HttpClient {
     return this.parseMutationResponse(response);
   }
 };
+var ReadOnlyCollectionClient = class extends HttpClient {
+  from(collection) {
+    return new ReadOnlyCollectionQueryBuilder(this, collection);
+  }
+  async requestFind(endpoint, options) {
+    const url = this.buildUrl(endpoint, options);
+    const response = await this.fetchWithTracking(url, {
+      ...this.defaultOptions,
+      method: "GET"
+    });
+    return this.parseFindResponse(response);
+  }
+  async requestFindById(endpoint, options) {
+    const url = this.buildUrl(endpoint, options);
+    const response = await this.fetchWithTracking(url, {
+      ...this.defaultOptions,
+      method: "GET"
+    });
+    return this.parseDocumentResponse(response);
+  }
+  async requestCount(endpoint, options) {
+    const url = this.buildUrl(endpoint, options);
+    const response = await this.fetchWithTracking(url, {
+      ...this.defaultOptions,
+      method: "GET"
+    });
+    return this.parseDocumentResponse(response);
+  }
+};
 
 // src/core/collection/const.ts
 var INTERNAL_COLLECTIONS = [
@@ -1084,6 +1238,7 @@ var INTERNAL_COLLECTIONS = [
   "api-keys",
   "personal-access-tokens",
   "tenant-entitlements",
+  "direct-upload-sessions",
   "webhook-events",
   "webhook-deliveries",
   "audit-logs",
@@ -1220,7 +1375,11 @@ async function parseApiResponse(response, endpoint) {
 // src/core/community/community-client.ts
 var CommunityClient = class {
   constructor(options) {
-    this.publishableKey = options.publishableKey ?? "";
+    this.publishableKey = requirePublishableKeyForSecret(
+      "CommunityClient",
+      options.publishableKey,
+      options.secretKey
+    );
     this.secretKey = options.secretKey;
     this.customerToken = options.customerToken;
     this.onUnauthorized = options.onUnauthorized;
@@ -1390,7 +1549,11 @@ var BaseApi = class {
     if (!options.secretKey) {
       throw createConfigError(`secretKey is required for ${apiName}.`);
     }
-    this.publishableKey = options.publishableKey ?? "";
+    this.publishableKey = requirePublishableKeyForSecret(
+      apiName,
+      options.publishableKey,
+      options.secretKey
+    );
     this.secretKey = options.secretKey;
     this.onRequestId = options.onRequestId;
   }
@@ -1684,7 +1847,11 @@ var CartApi = class {
         "Either secretKey or customerToken is required for CartApi."
       );
     }
-    this.publishableKey = options.publishableKey ?? "";
+    this.publishableKey = requirePublishableKeyForSecret(
+      "CartApi",
+      options.publishableKey,
+      options.secretKey
+    );
     this.secretKey = options.secretKey;
     this.customerToken = options.customerToken;
     this.onUnauthorized = options.onUnauthorized;
@@ -1880,8 +2047,13 @@ var OrderApi = class extends BaseApi {
 // src/core/commerce/server-commerce-client.ts
 var ServerCommerceClient = class {
   constructor(options) {
+    const publishableKey = requirePublishableKeyForSecret(
+      "ServerCommerceClient",
+      options.publishableKey,
+      options.secretKey
+    );
     const serverOptions = {
-      publishableKey: options.publishableKey,
+      publishableKey,
       secretKey: options.secretKey,
       onRequestId: options.onRequestId
     };
@@ -2482,7 +2654,14 @@ var Client = class {
       onUnauthorized,
       onRequestId
     });
-    this.collections = new CollectionClient(
+    const collectionClient = new CollectionClient(
+      this.config.publishableKey,
+      void 0,
+      () => this.customer.auth.getToken(),
+      onUnauthorized,
+      onRequestId
+    );
+    this.collections = new ReadOnlyCollectionClient(
       this.config.publishableKey,
       void 0,
       () => this.customer.auth.getToken(),
@@ -2491,7 +2670,7 @@ var Client = class {
     );
     this.query = new QueryHooks(
       this.queryClient,
-      this.collections,
+      collectionClient,
       this.customer.auth
     );
   }