@granular-software/sdk 0.4.4 → 0.4.5

package/README.md

@@ -33,7 +33,7 @@ Inside this monorepo, prefer the workspace package instead of installing from np
 By default, the SDK resolves endpoints like this:
 
 - Local mode (`NODE_ENV=development`): `ws://localhost:8787/granular`
-- Production mode (default): `wss://api.granular.dev/v2/ws`
+- Production mode (default): `wss://cf-api-gateway.arthur6084.workers.dev/granular`
 
 Overrides:
 

package/dist/cli/index.js

@@ -5387,7 +5387,7 @@ var import_dotenv = __toESM(require_main());
 
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
-var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
 var LOCAL_AUTH_URL = "http://localhost:3000";
 var PRODUCTION_AUTH_URL = "https://app.granular.software";
 function readEnv(name) {
@@ -5775,6 +5775,9 @@ var ApiClient = class {
       return false;
     }
   }
+  async validateKeyOrThrow() {
+    await this.request("/control/sandboxes");
+  }
   // ── Sandboxes ──
   async listSandboxes() {
     const result = await this.request("/control/sandboxes");
@@ -7847,9 +7850,11 @@ async function initCommand(projectName, options) {
   const apiUrl = loadApiUrl();
   const api = new ApiClient(apiKey, apiUrl);
   const validating = spinner("Validating API key...");
-  const isValid = await api.validateKey();
-  if (!isValid) {
-    validating.fail("  Invalid API key. Please check your key and try again.");
+  try {
+    await api.validateKeyOrThrow();
+  } catch (err) {
+    const detail = err?.message ? ` (${err.message})` : "";
+    validating.fail(`  API key validation failed${detail}.`);
     process.exit(1);
   }
   validating.succeed("  API key validated.");
@@ -8015,9 +8020,11 @@ async function loginCommand(options = {}) {
   }
   const spinner2 = spinner("Validating...");
   const api = new ApiClient(apiKey, apiUrl);
-  const valid = await api.validateKey();
-  if (!valid) {
-    spinner2.fail("  Invalid API key.");
+  try {
+    await api.validateKeyOrThrow();
+  } catch (err) {
+    const detail = err?.message ? ` (${err.message})` : "";
+    spinner2.fail(`  API key validation failed${detail}.`);
     process.exit(1);
   }
   saveApiKey(apiKey);

package/dist/index.d.mts

@@ -88,6 +88,11 @@ interface ConnectOptions {
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
      *  value for long-lived effect hosts so tool catalogs don't accumulate. */
     clientId?: string;
+    /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
+    initialHeap?: Array<{
+        className: string;
+        id: string;
+    }>;
 }
 /**
  * A sandbox container
@@ -454,6 +459,47 @@ interface Prompt {
     options?: string[];
     defaultValue?: unknown;
 }
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+interface SessionHeapFieldValue {
+    name: string;
+    type: SessionHeapFieldType;
+    value: string | number | boolean | null;
+}
+interface SessionHeapEntry {
+    path: string;
+    className: string;
+    id: string;
+    label?: string | null;
+    description?: string | null;
+    prototypes: string[];
+    fields: SessionHeapFieldValue[];
+    relatedJobIds: string[];
+    source: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionHeapList {
+    name: string;
+    className: string;
+    paths: string[];
+    relatedJobIds: string[];
+    updatedAt: number;
+}
+interface SessionHeapVariable {
+    name: string;
+    kind: 'entry' | 'list' | 'scalar';
+    entryPath?: string;
+    listName?: string;
+    value?: string | number | boolean | null;
+    className?: string;
+    updatedAt: number;
+}
+interface SessionHeapSnapshot {
+    entriesByPath: Record<string, SessionHeapEntry>;
+    listsByName: Record<string, SessionHeapList>;
+    variablesByName: Record<string, SessionHeapVariable>;
+    updatedAt: number;
+}
 interface WSDisconnectInfo {
     code?: number;
     reason?: string;
@@ -974,6 +1020,13 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /**
+     * Return a plain JS snapshot of the synced session heap.
+     *
+     * The heap lives in the Automerge document, so this method does not perform
+     * any extra network roundtrip.
+     */
+    getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
     /**
      * Close the session and disconnect from the sandbox.
@@ -1427,4 +1480,4 @@ declare class Granular {
     private request;
 }
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };

package/dist/index.d.ts

@@ -88,6 +88,11 @@ interface ConnectOptions {
     /** Optional stable client ID. Defaults to `client_${Date.now()}`. Use a fixed
      *  value for long-lived effect hosts so tool catalogs don't accumulate. */
     clientId?: string;
+    /** Optional session heap seed. Each item is eagerly hydrated into the session heap on connect. */
+    initialHeap?: Array<{
+        className: string;
+        id: string;
+    }>;
 }
 /**
  * A sandbox container
@@ -454,6 +459,47 @@ interface Prompt {
     options?: string[];
     defaultValue?: unknown;
 }
+type SessionHeapFieldType = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+interface SessionHeapFieldValue {
+    name: string;
+    type: SessionHeapFieldType;
+    value: string | number | boolean | null;
+}
+interface SessionHeapEntry {
+    path: string;
+    className: string;
+    id: string;
+    label?: string | null;
+    description?: string | null;
+    prototypes: string[];
+    fields: SessionHeapFieldValue[];
+    relatedJobIds: string[];
+    source: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionHeapList {
+    name: string;
+    className: string;
+    paths: string[];
+    relatedJobIds: string[];
+    updatedAt: number;
+}
+interface SessionHeapVariable {
+    name: string;
+    kind: 'entry' | 'list' | 'scalar';
+    entryPath?: string;
+    listName?: string;
+    value?: string | number | boolean | null;
+    className?: string;
+    updatedAt: number;
+}
+interface SessionHeapSnapshot {
+    entriesByPath: Record<string, SessionHeapEntry>;
+    listsByName: Record<string, SessionHeapList>;
+    variablesByName: Record<string, SessionHeapVariable>;
+    updatedAt: number;
+}
 interface WSDisconnectInfo {
     code?: number;
     reason?: string;
@@ -974,6 +1020,13 @@ declare class Environment extends Session {
     get permissionProfileId(): string;
     /** The GraphQL API endpoint URL */
     get apiEndpoint(): string;
+    /**
+     * Return a plain JS snapshot of the synced session heap.
+     *
+     * The heap lives in the Automerge document, so this method does not perform
+     * any extra network roundtrip.
+     */
+    getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
     /**
      * Close the session and disconnect from the sandbox.
@@ -1427,4 +1480,4 @@ declare class Granular {
     private request;
 }
 
-export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };
+export { type APIError, type AccessTokenProvider, type Assignment, type AssignmentListResponse, type Build, type BuildListResponse, type BuildPolicy, type BuildStatus, type ConnectOptions, type CreateEnvironmentData, type CreatePermissionProfileData, type CreateSandboxData, type DefineRelationshipOptions, type DeleteResponse, type DomainState, type EffectHandler, type EffectHandlerContext, type EffectInfo, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobStatus, type JobSubmitResult, type Manifest, type ManifestContent, type ManifestEffectDeclaration, type ManifestEffectSchema, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type Sandbox, type SandboxListResponse, Session, type SessionHeapEntry, type SessionHeapFieldType, type SessionHeapFieldValue, type SessionHeapList, type SessionHeapSnapshot, type SessionHeapVariable, type Subject, type SyncMessage, type ToolHandler, type ToolInfo, type ToolInvokeParams, type ToolResultParams, type ToolSchema, type ToolWithHandler, type ToolsChangedEvent, type User, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo };

package/dist/index.js

@@ -5089,7 +5089,7 @@ var JobImplementation = class {
 
 // src/endpoints.ts
 var LOCAL_API_URL = "ws://localhost:8787/granular";
-var PRODUCTION_API_URL = "wss://api.granular.dev/v2/ws";
+var PRODUCTION_API_URL = "wss://cf-api-gateway.arthur6084.workers.dev/granular";
 function readEnv(name) {
   if (typeof process === "undefined" || !process.env) return void 0;
   return process.env[name];
@@ -5176,6 +5176,26 @@ function buildEffectHostUrl(apiUrl, sandboxId, effectClientId, clientId) {
   url.searchParams.set("clientId", clientId);
   return url.toString();
 }
+function createEmptyHeapSnapshot(now = Date.now()) {
+  return {
+    entriesByPath: {},
+    listsByName: {},
+    variablesByName: {},
+    updatedAt: now
+  };
+}
+function normalizeHeapSnapshot(raw) {
+  if (!raw || typeof raw !== "object") {
+    return createEmptyHeapSnapshot();
+  }
+  const heap = raw;
+  return {
+    entriesByPath: heap.entriesByPath && typeof heap.entriesByPath === "object" ? JSON.parse(JSON.stringify(heap.entriesByPath)) : {},
+    listsByName: heap.listsByName && typeof heap.listsByName === "object" ? JSON.parse(JSON.stringify(heap.listsByName)) : {},
+    variablesByName: heap.variablesByName && typeof heap.variablesByName === "object" ? JSON.parse(JSON.stringify(heap.variablesByName)) : {},
+    updatedAt: typeof heap.updatedAt === "number" ? heap.updatedAt : Date.now()
+  };
+}
 var Environment = class _Environment extends Session {
   envData;
   _apiKey;
@@ -5206,6 +5226,16 @@ var Environment = class _Environment extends Session {
   get apiEndpoint() {
     return this._apiEndpoint;
   }
+  /**
+   * Return a plain JS snapshot of the synced session heap.
+   *
+   * The heap lives in the Automerge document, so this method does not perform
+   * any extra network roundtrip.
+   */
+  getHeap() {
+    const doc = this.document;
+    return normalizeHeapSnapshot(doc?.heap);
+  }
   getRuntimeBaseUrl() {
     try {
       const endpoint = new URL(this._apiEndpoint);
@@ -6067,7 +6097,8 @@ var Granular = class {
       method: "POST",
       body: JSON.stringify({
         environmentId: envData.environmentId,
-        clientId
+        clientId,
+        initialHeap: options.initialHeap
       })
     });
     const client = new WSClient({