@gravity-rail/sdk 0.36.0 → 0.40.0

package/README.md

@@ -22,6 +22,11 @@ npm install zod  # optional, for runtime validation
 
 ## Quick Start
 
+Create an account or organization API key with the scopes your integration needs.
+See [Authentication](https://docs.gravityrail.com/developer/guides/connect/authentication)
+for key reach, OAuth, and step-up requirements. Keep credentials in your server's
+environment or secrets manager; do not embed an API key in a public browser bundle.
+
 ```typescript
 import { GravityRailClient } from '@gravity-rail/sdk';
 
@@ -30,26 +35,55 @@ const client = new GravityRailClient(
   'https://api.gravityrail.com'
 );
 
-// List all workflows in a workspace
+const workspaces = await client.getWorkspaces();
+if (workspaces.length === 0) throw new Error('No workspace available');
+const workspaceId = workspaces[0].id;
 const workflows = await client.getWorkflows(workspaceId);
-
-// Get active chats across every channel
 const chats = await client.getChats(workspaceId);
+```
+
+Use [Creating Members](https://docs.gravityrail.com/developer/guides/data/creating-members)
+to select the appropriate creation/import endpoint and role. A direct SDK call
+uses the request type's wire names:
 
-// Create a new member
+```typescript
+const roleId = Number(process.env.GRAVITY_RAIL_MEMBER_ROLE_ID);
+if (!Number.isInteger(roleId) || roleId <= 0) {
+  throw new Error('Set GRAVITY_RAIL_MEMBER_ROLE_ID to an authorized role ID');
+}
 const member = await client.createWorkspaceMember(workspaceId, {
-  first_name: 'Jane',
-  last_name: 'Doe',
-  email: 'jane@example.com',
-  role_id: roleId,
+  name: 'Integration Test',
+  email: 'integration-test@example.com',
+  memberRoleId: roleId, // an authorized role selected for the new Member
 });
 ```
 
+### Handle API errors
+
+```typescript
+import { ApiError } from '@gravity-rail/sdk';
+
+try {
+  await client.getWorkflows(workspaceId);
+} catch (error) {
+  if (error instanceof ApiError && error.statusCode === 403) {
+    // Check the acting identity and scopes for this workspace.
+  }
+  throw error;
+}
+```
+
+See [Error Handling](https://docs.gravityrail.com/developer/guides/connect/error-handling)
+for status codes and safe reporting. The [SDK Reference](https://docs.gravityrail.com/sdk)
+and [GravityRailClient](https://docs.gravityrail.com/sdk/classes/GravityRailClient)
+reference document methods and types. This package README also supplies the
+canonical [SDK usage guide](https://docs.gravityrail.com/developer/libraries/sdk).
+
 ## Authentication
 
 ### API Key
 
-Scoped API keys are the simplest way to authenticate. Create one from workspace settings or via the SDK:
+Create an account or organization API key with the required permissions:
 
 ```typescript
 const client = new GravityRailClient(
@@ -58,7 +92,7 @@ const client = new GravityRailClient(
 );
 ```
 
-Keys can be scoped to specific permissions (read-only, workspace-limited, time-expiring) using the [granular scope system](#scopes--permissions).
+Select the required scopes and expiry using the [granular scope system](#scopes--permissions). Key reach depends on the issuing account or organization; a key created in workspace settings is not inherently limited to that workspace.
 
 ### OAuth2 with PKCE
 
@@ -73,17 +107,6 @@ client.setEnhancedAuthHandler(async (authInfo) => {
 });
 ```
 
-### Member Identity Switching
-
-Act on behalf of a specific workspace member:
-
-```typescript
-client.setActingMember(memberUuid);
-// All subsequent requests use this member's identity
-const myChats = await client.getChats(workspaceId);
-client.setActingMember(undefined); // reset
-```
-
 ## Core Concepts
 
 Every Gravity Rail workspace is a self-contained environment with isolated data, workflows, and configuration. The SDK organizes its 500+ methods by domain:

package/dist/agui.d.cts

@@ -1,4 +1,4 @@
-import { C as ChannelEvent } from './types-0c6_NGU4.cjs';
+import { C as ChannelEvent } from './types-DlfADjPR.cjs';
 
 interface TranscriptMessage {
     id: string;

package/dist/agui.d.ts

@@ -1,4 +1,4 @@
-import { C as ChannelEvent } from './types-0c6_NGU4.js';
+import { C as ChannelEvent } from './types-DlfADjPR.js';
 
 interface TranscriptMessage {
     id: string;

package/dist/audio.d.cts

@@ -1,4 +1,4 @@
-import { C as ChannelEvent } from './types-0c6_NGU4.cjs';
+import { C as ChannelEvent } from './types-DlfADjPR.cjs';
 
 /** PCM16 helpers aligned with main-app web voice (24 kHz). */
 declare const SERVER_SAMPLE_RATE = 24000;

package/dist/audio.d.ts

@@ -1,4 +1,4 @@
-import { C as ChannelEvent } from './types-0c6_NGU4.js';
+import { C as ChannelEvent } from './types-DlfADjPR.js';
 
 /** PCM16 helpers aligned with main-app web voice (24 kHz). */
 declare const SERVER_SAMPLE_RATE = 24000;