@mybe/sdk 1.0.6 → 1.1.1

package/README.md

@@ -12,7 +12,7 @@ npm install @mybe/sdk
 
 - ✅ **Zero Dependencies** - Uses native fetch API
 - ✅ **TypeScript Support** - Full type safety with TypeScript
-- ✅ **Auto Environment Detection** - Automatically detects development vs production
+- ✅ **Environment Support** - Query content from different environments (master, staging, development)
 - ✅ **Error Handling** - Custom error classes for better error handling
 - ✅ **Pagination Support** - Built-in pagination for large datasets
 - ✅ **Status Filtering** - Filter content by status (draft, published, archived)
@@ -46,22 +46,77 @@ const contentList = await sdk.getContentByType('content-type-id', {
 ```typescript
 const sdk = new MybeSDK({
   apiKey: 'your-api-key'
+  // Defaults to 'master' environment
 });
 ```
 
-The SDK automatically detects the environment:
-- **Development** (`NODE_ENV=development`): Uses `https://sdk-dev.contensa.ai/dev/api/v1`
-- **Production**: Uses `https://sdk-dev.contensa.ai/dev/api/v1`
+### Environment Configuration
 
-> **Note:** The SDK uses a custom domain for all environments, providing a professional branded URL while hiding the underlying AWS infrastructure. Both development and production currently point to the same endpoint temporarily.
+Mybe CMS supports multiple environments for content isolation. Each SDK instance is locked to a specific environment.
+
+```typescript
+// Production environment (default)
+const prodClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'master' // or omit for default
+});
+
+// Staging environment
+const stagingClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'staging'
+});
+
+// Development environment
+const devClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'development'
+});
+
+// Custom environment (by slug or UUID)
+const customClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'my-custom-env'
+});
+```
+
+**Environment Best Practices:**
+
+1. **Master Environment** - Your production content (default)
+2. **Staging Environment** - Test changes before production
+3. **Development Environment** - Active development work
+4. **Custom Environments** - Feature branches, testing, etc.
+
+**Important:** Each client instance is locked to its environment. To query different environments, create separate client instances.
+
+```typescript
+// ✅ Correct: Separate clients for different environments
+const prodPosts = await prodClient.getContentByType('blog-post-id');
+const stagingPosts = await stagingClient.getContentByType('blog-post-id');
+
+// ❌ Incorrect: Cannot switch environments on the same client
+// You must create a new client instance
+```
 
 ### Custom Base URL (Optional)
 
 ```typescript
 const sdk = new MybeSDK({
   apiKey: 'your-api-key',
-  baseUrl: 'https://custom-api.example.com/api/v1'
+  baseUrl: 'https://custom-api.example.com/api/v1',
+  environment: 'staging'
+});
+```
+
+### Getting Current Environment
+
+```typescript
+const sdk = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'staging'
 });
+
+console.log(sdk.getEnvironment()); // 'staging'
 ```
 
 ## API Reference
@@ -255,10 +310,102 @@ interface ContentEntry {
 
 ## Examples
 
+### Environment-based Workflows
+
+#### Development → Staging → Production
+
+```typescript
+import { MybeSDK } from '@mybe/sdk';
+
+// Create separate clients for each environment
+const devClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'development'
+});
+
+const stagingClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'staging'
+});
+
+const prodClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'master'
+});
+
+// Development: Work with draft content
+const draftPosts = await devClient.getContentByType('blog-post-id', {
+  status: 'draft',
+  limit: 10
+});
+
+// Staging: Test published content
+const stagingPosts = await stagingClient.getContentByType('blog-post-id', {
+  status: 'published',
+  limit: 10
+});
+
+// Production: Serve live content
+const livePosts = await prodClient.getContentByType('blog-post-id', {
+  status: 'published',
+  limit: 10
+});
+```
+
+#### Environment-aware Application
+
+```typescript
+// Automatically select environment based on NODE_ENV
+const getSDKClient = () => {
+  const apiKey = process.env.MYBE_API_KEY!;
+  
+  switch (process.env.NODE_ENV) {
+    case 'production':
+      return new MybeSDK({ apiKey, environment: 'master' });
+    case 'staging':
+      return new MybeSDK({ apiKey, environment: 'staging' });
+    case 'development':
+    default:
+      return new MybeSDK({ apiKey, environment: 'development' });
+  }
+};
+
+const sdk = getSDKClient();
+console.log(`Using environment: ${sdk.getEnvironment()}`);
+```
+
+#### Preview Mode (Staging vs Production)
+
+```typescript
+// Next.js example: Preview mode with environments
+export async function getStaticProps({ preview = false }) {
+  const sdk = new MybeSDK({
+    apiKey: process.env.MYBE_API_KEY!,
+    environment: preview ? 'staging' : 'master'
+  });
+  
+  const posts = await sdk.getContentByType('blog-post-id', {
+    status: preview ? 'draft' : 'published',
+    limit: 20
+  });
+  
+  return {
+    props: {
+      posts: posts.data,
+      preview
+    },
+    revalidate: 60
+  };
+}
+```
+
 ### Fetch Published Blog Posts
 
 ```typescript
-const sdk = new MybeSDK({ apiKey: 'your-api-key' });
+const sdk = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'master' // Production content
+});
 
 const posts = await sdk.getContentByType('blog-post-type-id', {
   status: 'published',
@@ -274,6 +421,8 @@ posts.data.forEach(post => {
 ### Fetch All Content Models
 
 ```typescript
+const sdk = new MybeSDK({ apiKey: 'your-api-key' });
+
 const contentModels = await sdk.getContentModels('project-id');
 
 contentModels.forEach(model => {
@@ -284,12 +433,42 @@ contentModels.forEach(model => {
 ### Fetch Single Content Entry
 
 ```typescript
+const sdk = new MybeSDK({ apiKey: 'your-api-key' });
+
 const content = await sdk.getContent('content-entry-id');
 
 console.log(content.data); // Your content data
 console.log(content.status); // draft | published | archived
 ```
 
+### Compare Content Across Environments
+
+```typescript
+const masterClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'master'
+});
+
+const stagingClient = new MybeSDK({
+  apiKey: 'your-api-key',
+  environment: 'staging'
+});
+
+// Fetch from both environments in parallel
+const [masterContent, stagingContent] = await Promise.all([
+  masterClient.getContentByType('blog-post-id', { limit: 10 }),
+  stagingClient.getContentByType('blog-post-id', { limit: 10 })
+]);
+
+console.log(`Master has ${masterContent.data.length} posts`);
+console.log(`Staging has ${stagingContent.data.length} posts`);
+
+// Find differences
+const masterIds = new Set(masterContent.data.map(p => p.id));
+const stagingOnly = stagingContent.data.filter(p => !masterIds.has(p.id));
+console.log(`${stagingOnly.length} posts only in staging`);
+```
+
 ### Multi-locale Content
 
 Fetch content in different languages using the locale filter:

package/dist/client.d.ts

@@ -2,9 +2,25 @@ import { MybeSDKConfig, ContentType, ContentEntry, ContentFilterOptions, Content
 export declare class MybeSDK {
     private apiKey;
     private baseUrl;
+    private environment;
     constructor(config: MybeSDKConfig);
+    /**
+     * Get the current environment this SDK instance is configured for
+     *
+     * @returns The environment identifier (slug or UUID)
+     *
+     * @example
+     * const sdk = new MybeSDK({ apiKey: 'key', environment: 'staging' });
+     * console.log(sdk.getEnvironment()); // 'staging'
+     */
+    getEnvironment(): string;
     /**
      * Make HTTP request to API
+     *
+     * Automatically includes:
+     * - API key authentication
+     * - Environment context header
+     * - Content-Type header
      */
     private request;
     /**

package/dist/client.js

@@ -2,33 +2,67 @@ import { MybeSDKError, NotFoundError, UnauthorizedError, ValidationError, Server
 export class MybeSDK {
     apiKey;
     baseUrl;
+    environment;
     constructor(config) {
         if (!config.apiKey) {
             throw new MybeSDKError('API key is required');
         }
-        this.apiKey = config.apiKey;
-        if (config.baseUrl) {
-            this.baseUrl = config.baseUrl;
+        // Validate API key format (basic check)
+        if (typeof config.apiKey !== 'string' || config.apiKey.trim().length === 0) {
+            throw new MybeSDKError('API key must be a non-empty string');
+        }
+        this.apiKey = config.apiKey.trim();
+        this.baseUrl = config.baseUrl || 'https://sdk.contensa.ai/v1/api/v1';
+        // Environment handling with validation
+        if (config.environment !== undefined) {
+            // Validate environment format
+            if (typeof config.environment !== 'string') {
+                throw new MybeSDKError('Environment must be a string');
+            }
+            const trimmedEnv = config.environment.trim();
+            if (trimmedEnv.length === 0) {
+                throw new MybeSDKError('Environment cannot be an empty string');
+            }
+            // Validate environment slug format (alphanumeric, hyphens, underscores)
+            // Supports both slugs (e.g., 'staging') and UUIDs
+            const isValidSlug = /^[a-z0-9][a-z0-9-_]*$/i.test(trimmedEnv);
+            const isValidUUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trimmedEnv);
+            if (!isValidSlug && !isValidUUID) {
+                throw new MybeSDKError('Environment must be a valid slug (alphanumeric with hyphens/underscores) or UUID');
+            }
+            this.environment = trimmedEnv;
         }
         else {
-            const isDevelopment = typeof process !== 'undefined' &&
-                process.env.CONTENSA_SDK_ENV === 'development';
-            // Use custom domain for SDK endpoints
-            // TODO: Update production URL when production custom domain is ready
-            // Production: https://fizsdck7l0.execute-api.us-east-1.amazonaws.com/dev/api/v1
-            this.baseUrl = isDevelopment
-                ? 'https://sdk-dev.contensa.ai/dev/api/v1'
-                : 'https://sdk.contensa.ai/dev/api/v1'; // Using dev URL for both temporarily
+            // Default to 'master' environment for backward compatibility
+            this.environment = 'master';
         }
     }
+    /**
+     * Get the current environment this SDK instance is configured for
+     *
+     * @returns The environment identifier (slug or UUID)
+     *
+     * @example
+     * const sdk = new MybeSDK({ apiKey: 'key', environment: 'staging' });
+     * console.log(sdk.getEnvironment()); // 'staging'
+     */
+    getEnvironment() {
+        return this.environment;
+    }
     /**
      * Make HTTP request to API
+     *
+     * Automatically includes:
+     * - API key authentication
+     * - Environment context header
+     * - Content-Type header
      */
     async request(endpoint, options = {}) {
         const url = `${this.baseUrl}${endpoint}`;
         const headers = {
             'Content-Type': 'application/json',
             'X-API-Key': this.apiKey,
+            'x-environment-id': this.environment, // Send environment with every request
             ...options.headers,
         };
         try {
@@ -149,6 +183,9 @@ export class MybeSDK {
         if (options.lastKey) {
             params.append('lastKey', encodeURIComponent(options.lastKey));
         }
+        if (options.include !== undefined) {
+            params.append('include', options.include.toString());
+        }
         const queryString = params.toString();
         return queryString ? `?${queryString}` : '';
     }
@@ -178,7 +215,9 @@ export class MybeSDK {
      */
     async getContentByType(contentTypeId, options) {
         const queryString = this.buildQueryString(options);
-        return await this.request(`/type/${contentTypeId}${queryString}`);
+        const endpoint = `/type/${contentTypeId}${queryString}`;
+        console.log('🔍 Fetching from endpoint:', endpoint);
+        return await this.request(endpoint);
     }
     /**
      * Get all content entries for a project

package/dist/types.d.ts

@@ -4,6 +4,33 @@
 export interface MybeSDKConfig {
     apiKey: string;
     baseUrl?: string;
+    /**
+     * Environment to query content from.
+     *
+     * Environments allow you to maintain separate content for different stages
+     * of your workflow (e.g., development, staging, production).
+     *
+     * @default 'master' - The production environment
+     *
+     * @example
+     * // Production environment (default)
+     * const prodClient = new MybeSDK({ apiKey: 'key' });
+     *
+     * @example
+     * // Staging environment
+     * const stagingClient = new MybeSDK({
+     *   apiKey: 'key',
+     *   environment: 'staging'
+     * });
+     *
+     * @example
+     * // Development environment
+     * const devClient = new MybeSDK({
+     *   apiKey: 'key',
+     *   environment: 'development'
+     * });
+     */
+    environment?: string;
 }
 /**
  * Content Type (Content Model)
@@ -57,6 +84,7 @@ export interface PaginationOptions {
 export interface ContentFilterOptions extends PaginationOptions {
     status?: 'draft' | 'published' | 'archived';
     locale?: string;
+    include?: number;
 }
 /**
  * Pagination Response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mybe/sdk",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",