@mybe/sdk 1.0.6 → 1.1.2

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,24 +46,79 @@ 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
 
 ### Content Models (Content Types)
@@ -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,30 +433,61 @@ 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:
+Fetch content in different languages using the locale filter. **TypeScript will autocomplete all supported locale codes** when you type `locale: ''`:
 
 ```typescript
 const sdk = new MybeSDK({ apiKey: 'your-api-key' });
 
 // Fetch English content
+// TypeScript autocompletes: 'en-US', 'en-GB', 'en-CA', 'en-AU'
 const englishPosts = await sdk.getContentByType('blog-post-type-id', {
   status: 'published',
-  locale: 'en-US',
+  locale: 'en-US', // ✨ Autocomplete suggests all 31 supported locales!
   limit: 10
 });
 
 // Fetch Bangla content
 const banglaPosts = await sdk.getContentByType('blog-post-type-id', {
   status: 'published',
-  locale: 'bn-BD',
+  locale: 'bn-BD', // ✨ Type-safe locale codes
   limit: 10
 });
 
@@ -326,6 +506,22 @@ const spanishPosts = await sdk.getContentByType('blog-post-type-id', {
 });
 ```
 
+**TypeScript Autocomplete Support:**
+
+The SDK provides full TypeScript autocomplete for all 31 supported locales:
+
+```typescript
+import { SUPPORTED_LOCALES, type SupportedLocale } from '@mybe/sdk';
+
+// View all supported locales
+console.log(SUPPORTED_LOCALES);
+// ['en-US', 'bn-BD', 'fr-FR', 'es-ES', 'de-DE', 'it-IT', ...]
+
+// Use the type for type-safe locale handling
+const userLocale: SupportedLocale = 'ja-JP'; // ✅ Valid
+const invalidLocale: SupportedLocale = 'invalid'; // ❌ TypeScript error!
+```
+
 **Building a Multi-language Website:**
 
 ```typescript
@@ -346,12 +542,17 @@ localizedContent.data.forEach(item => {
 });
 ```
 
-**Supported Locales:**
-- `en-US` - English (United States)
-- `bn-BD` - Bangla (Bangladesh)
-- `fr-FR` - French (France)
-- `es-ES` - Spanish (Spain)
-- Custom locales as configured in your CMS
+**All Supported Locales:**
+
+The SDK supports 31 locales with full TypeScript autocomplete:
+
+- **English**: `en-US`, `en-GB`, `en-CA`, `en-AU`
+- **European**: `fr-FR`, `es-ES`, `de-DE`, `it-IT`, `pt-PT`, `nl-NL`, `sv-SE`, `pl-PL`, `ru-RU`
+- **Americas**: `pt-BR`, `es-MX`, `es-AR`, `fr-CA`
+- **Asia-Pacific**: `ja-JP`, `ko-KR`, `zh-CN`, `zh-TW`, `hi-IN`, `th-TH`, `vi-VN`, `id-ID`, `ms-MY`, `fil-PH`, `bn-BD`
+- **Middle East & Africa**: `ar-SA`, `tr-TR`, `he-IL`
+
+**Note:** When you type `locale: ''` in your IDE, TypeScript will show all available options!
 
 ## GraphQL API
 

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/index.d.ts

@@ -20,5 +20,5 @@
  * ```
  */
 export { MybeSDK } from './client.js';
-export { MybeSDKConfig, ContentType, ContentEntry, ContentFilterOptions, PaginationOptions, PaginationResponse, APIResponse, ContentListResponse, } from './types.js';
+export { MybeSDKConfig, ContentType, ContentEntry, ContentFilterOptions, PaginationOptions, PaginationResponse, APIResponse, ContentListResponse, SupportedLocale, SUPPORTED_LOCALES, } from './types.js';
 export { MybeSDKError, NotFoundError, UnauthorizedError, ValidationError, ServerError, ForbiddenError, } from './errors.js';

package/dist/index.js

@@ -20,4 +20,5 @@
  * ```
  */
 export { MybeSDK } from './client.js';
+export { SUPPORTED_LOCALES, } from './types.js';
 export { MybeSDKError, NotFoundError, UnauthorizedError, ValidationError, ServerError, ForbiddenError, } from './errors.js';

package/dist/types.d.ts

@@ -1,9 +1,63 @@
+/**
+ * Supported locale codes for content localization.
+ *
+ * These locales are supported by Mybe CMS for multi-language content.
+ * When you specify a locale in your queries, TypeScript will autocomplete
+ * with these values.
+ *
+ * Source: Synced from apps/web/lib/locales.ts
+ *
+ * @example
+ * ```typescript
+ * // TypeScript will autocomplete locale values
+ * const content = await sdk.getContentByType('blog-post-id', {
+ *   locale: 'en-US', // Autocomplete suggests all supported locales
+ *   status: 'published'
+ * });
+ * ```
+ */
+export declare const SUPPORTED_LOCALES: readonly ["en-US", "bn-BD", "fr-FR", "es-ES", "de-DE", "it-IT", "pt-PT", "nl-NL", "sv-SE", "pl-PL", "ru-RU", "pt-BR", "es-MX", "es-AR", "en-CA", "fr-CA", "ja-JP", "ko-KR", "zh-CN", "zh-TW", "hi-IN", "th-TH", "vi-VN", "id-ID", "ms-MY", "fil-PH", "ar-SA", "tr-TR", "he-IL", "en-GB", "en-AU"];
+/**
+ * Type representing all supported locale codes.
+ *
+ * This type provides autocomplete for locale values in your IDE.
+ *
+ * @example 'en-US' | 'fr-FR' | 'es-ES' | 'bn-BD' | ...
+ */
+export type SupportedLocale = typeof SUPPORTED_LOCALES[number];
 /**
  * SDK Configuration
  */
 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)
@@ -37,7 +91,14 @@ export interface ContentEntry {
     status: 'draft' | 'published' | 'archived';
     contentType?: ContentTypeMetadata;
     data: Record<string, any>;
-    locale?: string;
+    /**
+     * Locale code for this content entry.
+     *
+     * TypeScript will autocomplete with all supported locale codes.
+     *
+     * @example 'en-US' | 'fr-FR' | 'es-ES' | 'bn-BD' | ...
+     */
+    locale?: SupportedLocale;
     created_by: string;
     updated_by?: string;
     published_at?: string;
@@ -56,7 +117,25 @@ export interface PaginationOptions {
  */
 export interface ContentFilterOptions extends PaginationOptions {
     status?: 'draft' | 'published' | 'archived';
-    locale?: string;
+    /**
+     * Filter content by locale.
+     *
+     * TypeScript will autocomplete with all supported locale codes when you type.
+     *
+     * @example
+     * ```typescript
+     * // Get English content
+     * await sdk.getContentByType('blog-id', { locale: 'en-US' });
+     *
+     * // Get French content
+     * await sdk.getContentByType('blog-id', { locale: 'fr-FR' });
+     *
+     * // Get Bangla content
+     * await sdk.getContentByType('blog-id', { locale: 'bn-BD' });
+     * ```
+     */
+    locale?: SupportedLocale;
+    include?: number;
 }
 /**
  * Pagination Response

package/dist/types.js

@@ -1 +1,51 @@
-export {};
+/**
+ * Supported locale codes for content localization.
+ *
+ * These locales are supported by Mybe CMS for multi-language content.
+ * When you specify a locale in your queries, TypeScript will autocomplete
+ * with these values.
+ *
+ * Source: Synced from apps/web/lib/locales.ts
+ *
+ * @example
+ * ```typescript
+ * // TypeScript will autocomplete locale values
+ * const content = await sdk.getContentByType('blog-post-id', {
+ *   locale: 'en-US', // Autocomplete suggests all supported locales
+ *   status: 'published'
+ * });
+ * ```
+ */
+export const SUPPORTED_LOCALES = [
+    "en-US",
+    "bn-BD",
+    "fr-FR",
+    "es-ES",
+    "de-DE",
+    "it-IT",
+    "pt-PT",
+    "nl-NL",
+    "sv-SE",
+    "pl-PL",
+    "ru-RU",
+    "pt-BR",
+    "es-MX",
+    "es-AR",
+    "en-CA",
+    "fr-CA",
+    "ja-JP",
+    "ko-KR",
+    "zh-CN",
+    "zh-TW",
+    "hi-IN",
+    "th-TH",
+    "vi-VN",
+    "id-ID",
+    "ms-MY",
+    "fil-PH",
+    "ar-SA",
+    "tr-TR",
+    "he-IL",
+    "en-GB",
+    "en-AU",
+];

package/package.json

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