fireberry-api-client 1.0.2-beta.1.0 → 1.0.2-beta.1.2

package/README.md

@@ -7,6 +7,7 @@ A standalone, framework-agnostic TypeScript/JavaScript client for the Fireberry
 - Full TypeScript support with comprehensive type definitions
 - Zero runtime dependencies (uses native `fetch`)
 - Supports both ESM and CommonJS
+- **SDK integration** - works with `@fireberry/sdk` for iframe-based plugins and widgets
 - Automatic retry on rate limits (429)
 - Optional metadata and query result caching
 - Smart cache invalidation on mutations (auto-clears query cache when records are modified)
@@ -32,18 +33,20 @@ npm install fireberry-api-client@latest
 ### Import Paths
 
 ```typescript
-// Main export
+// Main export (supports both API and SDK modes)
 import { FireberryClient } from 'fireberry-api-client';
 
 // Utilities export
 import { getObjectIdFieldName } from 'fireberry-api-client/utils';
 
-// SDK adapter
-import { createSDKQueryBuilder } from 'fireberry-api-client/sdk';
+// SDK utilities (for standalone SDK usage)
+import { createSDKQueryBuilder, EnhancedSDK } from 'fireberry-api-client/sdk';
 ```
 
 ## Quick Start
 
+### With API Key (Node.js / External API)
+
 ```typescript
 import { FireberryClient } from 'fireberry-api-client';
 
@@ -61,18 +64,45 @@ const accounts = await client.query({
 console.log(accounts.records);
 ```
 
+### With SDK (Fireberry Plugins / Widgets)
+
+```typescript
+import FireberryClientSDK from '@fireberry/sdk/client';
+import { FireberryClient } from 'fireberry-api-client';
+
+// Initialize SDK
+const sdk = new FireberryClientSDK();
+await sdk.initializeContext();
+
+// Create client with SDK
+const client = new FireberryClient({ sdk });
+
+// Use all client features (CRUD via SDK messaging)
+const accounts = await client.queryBuilder()
+  .objectType(1)
+  .select('accountid', 'accountname')
+  .where('statuscode').equals('1')
+  .execute();
+```
+
 ## API Reference
 
 ### Client Configuration
 
 ```typescript
 const client = new FireberryClient({
-  apiKey: 'your-api-key',        // Required
+  // Authentication (at least one required)
+  apiKey: 'your-api-key',        // Optional, API key for HTTP API mode
+  sdk: sdkInstance,              // Optional, SDK instance for iframe mode
+
+  // HTTP Options (API mode only)
   baseUrl: 'https://api.fireberry.com', // Optional, default shown
   timeout: 30000,                // Optional, request timeout in ms
   retryOn429: true,              // Optional, auto-retry on rate limit
   maxRetries: 120,               // Optional, max retry attempts
   retryDelay: 1000,              // Optional, delay between retries in ms
+
+  // Caching Options
   cacheMetadata: false,          // Optional, enable metadata caching
   cacheTTL: 300000,              // Optional, metadata cache TTL in ms (5 min default)
   cacheQueryResults: false,      // Optional, enable query result caching
@@ -81,6 +111,12 @@ const client = new FireberryClient({
 });
 ```
 
+**Initialization Modes:**
+
+- **API-only mode**: Pass only `apiKey` - all operations use HTTP API
+- **SDK-only mode**: Pass only `sdk` - CRUD via iframe messaging (no metadata support)
+- **Hybrid mode**: Pass both `apiKey` and `sdk` - CRUD via SDK, metadata via API
+
 ### Query Records
 
 ```typescript
@@ -484,24 +520,75 @@ const promise = client.query({
 controller.abort();
 ```
 
-## SDK Adapter (for @fireberry/sdk)
+## SDK Integration (for @fireberry/sdk)
 
-If you're building embedded Fireberry widgets/plugins using `@fireberry/sdk`, you can use this library's utilities with the SDK adapter:
+If you're building embedded Fireberry widgets/plugins using `@fireberry/sdk`, you can integrate it with this library in two ways:
+
+### Option 1: Direct SDK Integration with FireberryClient (Recommended)
+
+Pass the SDK instance directly to FireberryClient for seamless integration with all client features:
 
 ```typescript
 import FireberryClientSDK from '@fireberry/sdk/client';
-import { createSDKQueryBuilder, EnhancedSDK } from 'fireberry-api-client/sdk';
+import { FireberryClient } from 'fireberry-api-client';
 
 // Initialize Fireberry SDK (runs in iframe)
 const sdk = new FireberryClientSDK();
 await sdk.initializeContext();
+
+// Create client with SDK (CRUD via SDK, metadata requires apiKey)
+const client = new FireberryClient({
+  sdk: sdk,
+  // Optional: Add apiKey for metadata operations
+  // apiKey: 'your-api-key',
+});
+
+// Use all regular client features
+const accounts = await client.queryBuilder()
+  .objectType(1)
+  .select('accountid', 'accountname')
+  .where('statuscode').equals('1')
+  .execute();
+
+// CRUD operations work through SDK
+await client.records.create(1, { accountname: 'New Account' });
 ```
 
-### Option 1: Query Builder Factory
+**Three initialization modes:**
 
+1. **SDK-only mode** - CRUD operations only (no metadata):
 ```typescript
+const client = new FireberryClient({ sdk });
+```
+
+2. **Hybrid mode** - SDK for CRUD, API for metadata (recommended):
+```typescript
+const client = new FireberryClient({
+  sdk,
+  apiKey: 'your-api-key',
+});
+```
+
+3. **API-only mode** - Traditional HTTP API:
+```typescript
+const client = new FireberryClient({
+  apiKey: 'your-api-key',
+});
+```
+
+### Option 2: Standalone SDK Utilities
+
+Use SDK-specific utilities from the `/sdk` export for more granular control:
+
+#### 2a. Query Builder Factory
+
+```typescript
+import FireberryClientSDK from '@fireberry/sdk/client';
 import { createSDKQueryBuilder } from 'fireberry-api-client/sdk';
 
+const sdk = new FireberryClientSDK();
+await sdk.initializeContext();
+
 const queryBuilder = createSDKQueryBuilder(sdk);
 
 // Build and execute queries with fluent API
@@ -513,7 +600,7 @@ const results = await queryBuilder(1) // 1 = Account
   .execute();
 ```
 
-### Option 2: Enhanced SDK Wrapper
+#### 2b. Enhanced SDK Wrapper
 
 ```typescript
 import { EnhancedSDK } from 'fireberry-api-client/sdk';
@@ -546,7 +633,7 @@ await enhanced.update(1, 'record-id', { accountname: 'Updated' });
 await enhanced.delete(1, 'record-id');
 ```
 
-### Option 3: Use QueryBuilder Directly
+#### 2c. Use QueryBuilder Directly
 
 ```typescript
 import { QueryBuilder } from 'fireberry-api-client';

package/dist/{excludedFields-CuQ8Dp-N.d.cts → excludedFields-Dk-ILROQ.d.cts}

@@ -1,3 +1,97 @@
+/**
+ * Type definitions for @fireberry/sdk compatibility
+ * These types mirror the Fireberry SDK's API for seamless integration
+ */
+/**
+ * Query payload expected by the Fireberry SDK
+ */
+interface SDKQueryPayload {
+    /** Comma-separated field names to return */
+    fields: string;
+    /** Query filter string */
+    query: string;
+    /** Number of records per page */
+    page_size?: number;
+    /** Page number (1-based) */
+    page_number?: number;
+}
+/**
+ * Response error from SDK
+ */
+interface SDKResponseError {
+    data: Record<string, unknown> & {
+        Message?: string;
+    };
+    status: number;
+    statusText: string;
+}
+/**
+ * Response data from SDK operations
+ */
+interface SDKResponseData<T = Record<string, unknown>> {
+    type?: string;
+    success: boolean;
+    data: T & {
+        requestId?: string;
+    };
+    error?: SDKResponseError;
+    isParentReady: boolean;
+    requestId: string;
+}
+/**
+ * Record details from SDK context
+ */
+interface SDKRecordDetails {
+    type?: number;
+    id?: string;
+}
+/**
+ * User details from SDK context
+ */
+interface SDKUserDetails {
+    fullName?: string;
+    id?: string;
+}
+/**
+ * SDK context information
+ */
+interface SDKContext {
+    user: SDKUserDetails;
+    record: SDKRecordDetails;
+}
+/**
+ * Generic payload type for create/update operations
+ */
+type SDKPayload = Record<string, unknown>;
+/**
+ * Fireberry SDK API interface
+ * Matches the API surface of @fireberry/sdk
+ */
+interface FireberrySDKAPI<TData = Record<string, unknown>> {
+    /** Query records with filtering and pagination */
+    query: (objectType: string | number, payload: SDKQueryPayload) => Promise<SDKResponseData<TData>>;
+    /** Create a new record */
+    create: <T extends SDKPayload>(objectType: string | number, payload: T) => Promise<SDKResponseData<TData>>;
+    /** Delete a record by ID */
+    delete: (objectType: string | number, recordId: string) => Promise<SDKResponseData<TData>>;
+    /** Update an existing record */
+    update: <T extends SDKPayload>(objectType: string | number, recordId: string, payload: T) => Promise<SDKResponseData<TData>>;
+}
+/**
+ * Fireberry SDK Client interface
+ * Matches the structure of FireberryClientSDK from @fireberry/sdk
+ */
+interface FireberrySDKClient<TData = Record<string, unknown>> {
+    /** Access to CRUD API methods */
+    readonly api: FireberrySDKAPI<TData>;
+    /** Current context (record and user info) - null if not initialized */
+    readonly context: SDKContext | null;
+    /** Initialize context from parent Fireberry window */
+    initializeContext(): Promise<FireberrySDKClient<TData>>;
+    /** Clean up event listeners and pending requests */
+    destroy(): void;
+}
+
 /**
  * Options for query operations
  */
@@ -641,4 +735,4 @@ declare function isExcludedFromStarQuery(objectType: string | number, fieldName:
  */
 declare function getExcludedFieldsForStarQuery(objectType: string | number): string[];
 
-export { type ConditionBuilder as C, type DateConditionBuilder as D, EXCLUDED_FIELDS_FOR_STAR_QUERY as E, FIELD_TYPE_IDS as F, OBJECT_ID_MAP as O, QueryBuilder as Q, type QueryOptions as a, type QueryResult$1 as b, type QueryConditionItem as c, type QuerySeparatorItem as d, escapeQueryValue as e, type QueryItem as f, type QueryOperator as g, type QueryExplainResult as h, FIELD_TYPE_MAPPINGS as i, OBJECT_NAME_MAP as j, getObjectIdFieldName as k, getNameFieldByObjectType as l, isPureDate as m, addDays as n, getToday as o, getStartOfWeek as p, getStartOfMonth as q, isExcludedFromStarQuery as r, sanitizeQuery as s, getExcludedFieldsForStarQuery as t };
+export { type ConditionBuilder as C, type DateConditionBuilder as D, EXCLUDED_FIELDS_FOR_STAR_QUERY as E, type FireberrySDKClient as F, OBJECT_ID_MAP as O, QueryBuilder as Q, type SDKQueryPayload as S, type QueryOptions as a, type QueryResult$1 as b, type QueryConditionItem as c, type QuerySeparatorItem as d, escapeQueryValue as e, type QueryItem as f, type QueryOperator as g, type QueryExplainResult as h, type FireberrySDKAPI as i, type SDKResponseData as j, type SDKContext as k, FIELD_TYPE_IDS as l, FIELD_TYPE_MAPPINGS as m, OBJECT_NAME_MAP as n, getObjectIdFieldName as o, getNameFieldByObjectType as p, isPureDate as q, addDays as r, sanitizeQuery as s, getToday as t, getStartOfWeek as u, getStartOfMonth as v, isExcludedFromStarQuery as w, getExcludedFieldsForStarQuery as x };

package/dist/{excludedFields-CuQ8Dp-N.d.ts → excludedFields-Dk-ILROQ.d.ts}

@@ -1,3 +1,97 @@
+/**
+ * Type definitions for @fireberry/sdk compatibility
+ * These types mirror the Fireberry SDK's API for seamless integration
+ */
+/**
+ * Query payload expected by the Fireberry SDK
+ */
+interface SDKQueryPayload {
+    /** Comma-separated field names to return */
+    fields: string;
+    /** Query filter string */
+    query: string;
+    /** Number of records per page */
+    page_size?: number;
+    /** Page number (1-based) */
+    page_number?: number;
+}
+/**
+ * Response error from SDK
+ */
+interface SDKResponseError {
+    data: Record<string, unknown> & {
+        Message?: string;
+    };
+    status: number;
+    statusText: string;
+}
+/**
+ * Response data from SDK operations
+ */
+interface SDKResponseData<T = Record<string, unknown>> {
+    type?: string;
+    success: boolean;
+    data: T & {
+        requestId?: string;
+    };
+    error?: SDKResponseError;
+    isParentReady: boolean;
+    requestId: string;
+}
+/**
+ * Record details from SDK context
+ */
+interface SDKRecordDetails {
+    type?: number;
+    id?: string;
+}
+/**
+ * User details from SDK context
+ */
+interface SDKUserDetails {
+    fullName?: string;
+    id?: string;
+}
+/**
+ * SDK context information
+ */
+interface SDKContext {
+    user: SDKUserDetails;
+    record: SDKRecordDetails;
+}
+/**
+ * Generic payload type for create/update operations
+ */
+type SDKPayload = Record<string, unknown>;
+/**
+ * Fireberry SDK API interface
+ * Matches the API surface of @fireberry/sdk
+ */
+interface FireberrySDKAPI<TData = Record<string, unknown>> {
+    /** Query records with filtering and pagination */
+    query: (objectType: string | number, payload: SDKQueryPayload) => Promise<SDKResponseData<TData>>;
+    /** Create a new record */
+    create: <T extends SDKPayload>(objectType: string | number, payload: T) => Promise<SDKResponseData<TData>>;
+    /** Delete a record by ID */
+    delete: (objectType: string | number, recordId: string) => Promise<SDKResponseData<TData>>;
+    /** Update an existing record */
+    update: <T extends SDKPayload>(objectType: string | number, recordId: string, payload: T) => Promise<SDKResponseData<TData>>;
+}
+/**
+ * Fireberry SDK Client interface
+ * Matches the structure of FireberryClientSDK from @fireberry/sdk
+ */
+interface FireberrySDKClient<TData = Record<string, unknown>> {
+    /** Access to CRUD API methods */
+    readonly api: FireberrySDKAPI<TData>;
+    /** Current context (record and user info) - null if not initialized */
+    readonly context: SDKContext | null;
+    /** Initialize context from parent Fireberry window */
+    initializeContext(): Promise<FireberrySDKClient<TData>>;
+    /** Clean up event listeners and pending requests */
+    destroy(): void;
+}
+
 /**
  * Options for query operations
  */
@@ -641,4 +735,4 @@ declare function isExcludedFromStarQuery(objectType: string | number, fieldName:
  */
 declare function getExcludedFieldsForStarQuery(objectType: string | number): string[];
 
-export { type ConditionBuilder as C, type DateConditionBuilder as D, EXCLUDED_FIELDS_FOR_STAR_QUERY as E, FIELD_TYPE_IDS as F, OBJECT_ID_MAP as O, QueryBuilder as Q, type QueryOptions as a, type QueryResult$1 as b, type QueryConditionItem as c, type QuerySeparatorItem as d, escapeQueryValue as e, type QueryItem as f, type QueryOperator as g, type QueryExplainResult as h, FIELD_TYPE_MAPPINGS as i, OBJECT_NAME_MAP as j, getObjectIdFieldName as k, getNameFieldByObjectType as l, isPureDate as m, addDays as n, getToday as o, getStartOfWeek as p, getStartOfMonth as q, isExcludedFromStarQuery as r, sanitizeQuery as s, getExcludedFieldsForStarQuery as t };
+export { type ConditionBuilder as C, type DateConditionBuilder as D, EXCLUDED_FIELDS_FOR_STAR_QUERY as E, type FireberrySDKClient as F, OBJECT_ID_MAP as O, QueryBuilder as Q, type SDKQueryPayload as S, type QueryOptions as a, type QueryResult$1 as b, type QueryConditionItem as c, type QuerySeparatorItem as d, escapeQueryValue as e, type QueryItem as f, type QueryOperator as g, type QueryExplainResult as h, type FireberrySDKAPI as i, type SDKResponseData as j, type SDKContext as k, FIELD_TYPE_IDS as l, FIELD_TYPE_MAPPINGS as m, OBJECT_NAME_MAP as n, getObjectIdFieldName as o, getNameFieldByObjectType as p, isPureDate as q, addDays as r, sanitizeQuery as s, getToday as t, getStartOfWeek as u, getStartOfMonth as v, isExcludedFromStarQuery as w, getExcludedFieldsForStarQuery as x };