@granular-software/sdk 0.4.1 → 0.4.3

package/dist/{types-BOPsFZYi.d.mts → types-C0AVRsVR.d.mts}

@@ -111,14 +111,21 @@ interface SandboxListResponse {
     items: Sandbox[];
 }
 /**
- * Rules defining what tools and resources are allowed/denied
+ * Rules defining what effects and resources are allowed or denied.
  */
 interface PermissionRules {
-    /** Tool access rules */
+    /** Effect access rules */
+    effects?: {
+        /** Patterns for allowed effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        allow?: string[];
+        /** Patterns for denied effects */
+        deny?: string[];
+    };
+    /** Legacy alias accepted by the backend while migrating to `effects`. */
     tools?: {
-        /** Patterns for allowed tools (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        /** Patterns for allowed effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
         allow?: string[];
-        /** Patterns for denied tools */
+        /** Patterns for denied effects */
         deny?: string[];
     };
     /** Resource access rules */
@@ -248,17 +255,31 @@ interface BuildListResponse {
     items: Build[];
 }
 /**
- * Tool handler for static/global tools: receives (params)
+ * Effect handler for static/global effects: receives (input, context)
  */
-type ToolHandler = (input: any) => Promise<unknown>;
+interface EffectHandlerContext {
+    effectClientId: string;
+    sandboxId: string;
+    environmentId: string;
+    sessionId: string;
+    tenantId?: string;
+    principalId?: string;
+    permissionProfileId?: string;
+    user: {
+        subjectId: string;
+        identityId?: string;
+        principalId?: string;
+    };
+}
+type ToolHandler = (input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
- * Tool handler for instance methods: receives (objectId, params)
+ * Effect handler for instance methods: receives (objectId, input, context)
  */
-type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
+type InstanceToolHandler = (id: string, input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
- * Tool schema for publishing to the server.
+ * Effect schema for declaring or registering an effect.
  *
- * Tools come in three flavours:
+ * Effects come in three flavours:
  *
  * 1. **Instance methods** — set `className`, omit `static`.
  *    In the sandbox: `tolkien.get_bio({ detailed: true })`
@@ -268,7 +289,7 @@ type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
  *    In the sandbox: `Author.search({ query: 'tolkien' })`
  *    Handler signature: `(params: any) => any`
  *
- * 3. **Global tools** — omit `className`.
+ * 3. **Global effects** — omit `className`.
  *    In the sandbox: `global_search({ query: 'rings' })`
  *    Handler signature: `(params: any) => any`
  *
@@ -277,9 +298,10 @@ type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
  * TypeScript declarations that sandbox code imports from `./sandbox-tools`.
  */
 interface ToolSchema {
+    effectKey?: string;
     name: string;
     description: string;
-    /** JSON Schema for the tool's input parameters */
+    /** JSON Schema for the effect input parameters */
     inputSchema: Record<string, unknown>;
     /**
      * JSON Schema for the tool's return value.
@@ -305,9 +327,9 @@ interface ToolSchema {
     };
     tags?: string[];
     /**
-     * The class this tool belongs to (e.g., `'author'`, `'book'`).
-     * When set, the tool becomes a method on the auto-generated class.
-     * Omit for global tools (standalone exported functions).
+     * The class this effect belongs to (e.g., `'author'`, `'book'`).
+     * When set, the effect becomes a method on the auto-generated class.
+     * Omit for global effects (standalone exported functions).
      */
     className?: string;
     /**
@@ -318,8 +340,9 @@ interface ToolSchema {
      */
     static?: boolean;
 }
+type EffectSchema = ToolSchema;
 /**
- * Tool with handler — what users provide to `publishTools()`.
+ * Effect with handler — what users provide to `registerEffect()`.
  *
  * - **Instance methods** (`className` set, `static` omitted):
  *   handler receives `(objectId: string, params: any)`
@@ -331,8 +354,9 @@ interface ToolSchema {
 interface ToolWithHandler extends ToolSchema {
     handler: ToolHandler | InstanceToolHandler;
 }
+type EffectWithHandler = ToolWithHandler;
 /**
- * Result from publishing tools
+ * Result from publishing or synchronizing effects
  */
 interface PublishToolsResult {
     accepted: boolean;
@@ -342,6 +366,7 @@ interface PublishToolsResult {
         reason: string;
     }>;
 }
+type PublishEffectsResult = PublishToolsResult;
 /**
  * Domain state response
  */
@@ -356,39 +381,48 @@ interface DomainState {
     [key: string]: unknown;
 }
 /**
- * Information about a published tool
+ * Information about a live or declared effect
  */
 interface ToolInfo {
-    /** Unique name of the tool */
+    effectKey?: string;
+    /** Unique name of the effect */
     name: string;
-    /** Description of what the tool does */
+    /** Description of what the effect does */
     description?: string;
-    /** JSON Schema for tool input */
+    /** JSON Schema for effect input */
     inputSchema?: Record<string, unknown>;
-    /** JSON Schema for tool output */
+    /** JSON Schema for effect output */
     outputSchema?: Record<string, unknown>;
-    /** Client ID that published this tool (absent for domain-only entries) */
+    /** Client ID that published this effect (absent for domain-only entries) */
     clientId?: string;
-    /** Whether the tool is ready for use (has a registered handler) */
+    /** Whether the effect is ready for use (has a registered handler) */
     ready: boolean;
-    /** Timestamp when the tool was published */
+    /** Timestamp when the effect was published */
     publishedAt?: number;
-    /** Class this tool belongs to (instance/static method) */
+    /** Class this effect belongs to (instance/static method) */
     className?: string;
     /** Whether this is a static method */
     static?: boolean;
 }
+interface EffectInfo extends ToolInfo {
+}
 /**
- * Event data when the list of available tools changes
+ * Event data when the list of available effects changes
  */
 interface ToolsChangedEvent {
-    /** The current list of all available tools */
+    /** The current list of all available effects */
     tools: ToolInfo[];
-    /** Names of tools that were added or updated */
+    /** Names of effects that were added or updated */
     added: string[];
-    /** Names of tools that were removed */
+    /** Names of effects that were removed */
     removed: string[];
 }
+interface EffectsChangedEvent extends ToolsChangedEvent {
+    /** The current list of all available effects */
+    effects: EffectInfo[];
+}
+type EffectHandler = ToolHandler;
+type InstanceEffectHandler = InstanceToolHandler;
 type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
 /**
  * Result from submitting a job
@@ -600,6 +634,24 @@ interface ManifestRelationshipDef {
     /** Whether the right side is a collection */
     rightIsMany: boolean;
 }
+interface ManifestEffectSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+    description?: string;
+    [key: string]: unknown;
+}
+interface ManifestEffectDeclaration {
+    name: string;
+    description?: string;
+    attachedClass?: string;
+    isStatic?: boolean;
+    inputSchema: ManifestEffectSchema;
+    outputSchema?: ManifestEffectSchema;
+    stability?: 'stable' | 'experimental' | 'deprecated';
+    tags?: string[];
+}
 /**
  * A single operation in a manifest volume
  */
@@ -616,6 +668,8 @@ interface ManifestOperation {
     has?: Record<string, ManifestPropertySpec>;
     /** Define a relationship between two classes */
     defineRelationship?: ManifestRelationshipDef;
+    /** Declare a build-owned effect */
+    withEffect?: ManifestEffectDeclaration;
 }
 /**
  * A volume in a manifest
@@ -669,4 +723,4 @@ interface DeleteResponse {
     deleted: boolean;
 }
 
-export type { ToolInvokeParams as $, AssignmentListResponse as A, BuildPolicy as B, ConnectOptions as C, DomainState as D, EnvironmentData as E, BuildStatus as F, GranularOptions as G, Build as H, InstanceToolHandler as I, Job as J, BuildListResponse as K, JobStatus as L, ModelRef as M, JobSubmitResult as N, Prompt as O, PublishToolsResult as P, WSDisconnectInfo as Q, RecordUserOptions as R, SandboxListResponse as S, ToolWithHandler as T, User as U, WSReconnectErrorInfo as V, WSClientOptions as W, RPCRequest as X, RPCResponse as Y, SyncMessage as Z, RPCRequestFromServer as _, ToolHandler as a, ToolResultParams as a0, ManifestPropertySpec as a1, ManifestRelationshipDef as a2, ManifestOperation as a3, ManifestImport as a4, ManifestVolume as a5, APIError as a6, ToolInfo as b, ToolsChangedEvent as c, GraphQLResult as d, DefineRelationshipOptions as e, RelationshipInfo as f, ManifestContent as g, RecordObjectOptions as h, RecordObjectResult as i, Sandbox as j, CreateSandboxData as k, DeleteResponse as l, PermissionProfile as m, CreatePermissionProfileData as n, CreateEnvironmentData as o, Subject as p, ToolSchema as q, AccessTokenProvider as r, EndpointMode as s, GranularAuth as t, PermissionRules as u, PermissionProfileListResponse as v, Assignment as w, EnvironmentListResponse as x, Manifest as y, ManifestListResponse as z };
+export type { JobSubmitResult as $, AssignmentListResponse as A, BuildPolicy as B, ConnectOptions as C, DomainState as D, EffectInfo as E, Manifest as F, GranularOptions as G, ManifestListResponse as H, InstanceToolHandler as I, Job as J, BuildStatus as K, Build as L, ModelRef as M, BuildListResponse as N, EffectHandlerContext as O, PublishToolsResult as P, EffectSchema as Q, RecordUserOptions as R, SandboxListResponse as S, ToolWithHandler as T, User as U, EffectWithHandler as V, WSClientOptions as W, PublishEffectsResult as X, EffectHandler as Y, InstanceEffectHandler as Z, JobStatus as _, ToolHandler as a, Prompt as a0, WSDisconnectInfo as a1, WSReconnectErrorInfo as a2, RPCRequest as a3, RPCResponse as a4, SyncMessage as a5, RPCRequestFromServer as a6, ToolInvokeParams as a7, ToolResultParams as a8, ManifestPropertySpec as a9, ManifestRelationshipDef as aa, ManifestEffectSchema as ab, ManifestEffectDeclaration as ac, ManifestOperation as ad, ManifestImport as ae, ManifestVolume as af, APIError as ag, ToolInfo as b, EffectsChangedEvent as c, ToolsChangedEvent as d, EnvironmentData as e, GraphQLResult as f, DefineRelationshipOptions as g, RelationshipInfo as h, ManifestContent as i, RecordObjectOptions as j, RecordObjectResult as k, Sandbox as l, CreateSandboxData as m, DeleteResponse as n, PermissionProfile as o, CreatePermissionProfileData as p, CreateEnvironmentData as q, Subject as r, ToolSchema as s, AccessTokenProvider as t, EndpointMode as u, GranularAuth as v, PermissionRules as w, PermissionProfileListResponse as x, Assignment as y, EnvironmentListResponse as z };

package/dist/{types-BOPsFZYi.d.ts → types-C0AVRsVR.d.ts}

@@ -111,14 +111,21 @@ interface SandboxListResponse {
     items: Sandbox[];
 }
 /**
- * Rules defining what tools and resources are allowed/denied
+ * Rules defining what effects and resources are allowed or denied.
  */
 interface PermissionRules {
-    /** Tool access rules */
+    /** Effect access rules */
+    effects?: {
+        /** Patterns for allowed effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        allow?: string[];
+        /** Patterns for denied effects */
+        deny?: string[];
+    };
+    /** Legacy alias accepted by the backend while migrating to `effects`. */
     tools?: {
-        /** Patterns for allowed tools (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        /** Patterns for allowed effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
         allow?: string[];
-        /** Patterns for denied tools */
+        /** Patterns for denied effects */
         deny?: string[];
     };
     /** Resource access rules */
@@ -248,17 +255,31 @@ interface BuildListResponse {
     items: Build[];
 }
 /**
- * Tool handler for static/global tools: receives (params)
+ * Effect handler for static/global effects: receives (input, context)
  */
-type ToolHandler = (input: any) => Promise<unknown>;
+interface EffectHandlerContext {
+    effectClientId: string;
+    sandboxId: string;
+    environmentId: string;
+    sessionId: string;
+    tenantId?: string;
+    principalId?: string;
+    permissionProfileId?: string;
+    user: {
+        subjectId: string;
+        identityId?: string;
+        principalId?: string;
+    };
+}
+type ToolHandler = (input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
- * Tool handler for instance methods: receives (objectId, params)
+ * Effect handler for instance methods: receives (objectId, input, context)
  */
-type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
+type InstanceToolHandler = (id: string, input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
- * Tool schema for publishing to the server.
+ * Effect schema for declaring or registering an effect.
  *
- * Tools come in three flavours:
+ * Effects come in three flavours:
  *
  * 1. **Instance methods** — set `className`, omit `static`.
  *    In the sandbox: `tolkien.get_bio({ detailed: true })`
@@ -268,7 +289,7 @@ type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
  *    In the sandbox: `Author.search({ query: 'tolkien' })`
  *    Handler signature: `(params: any) => any`
  *
- * 3. **Global tools** — omit `className`.
+ * 3. **Global effects** — omit `className`.
  *    In the sandbox: `global_search({ query: 'rings' })`
  *    Handler signature: `(params: any) => any`
  *
@@ -277,9 +298,10 @@ type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
  * TypeScript declarations that sandbox code imports from `./sandbox-tools`.
  */
 interface ToolSchema {
+    effectKey?: string;
     name: string;
     description: string;
-    /** JSON Schema for the tool's input parameters */
+    /** JSON Schema for the effect input parameters */
     inputSchema: Record<string, unknown>;
     /**
      * JSON Schema for the tool's return value.
@@ -305,9 +327,9 @@ interface ToolSchema {
     };
     tags?: string[];
     /**
-     * The class this tool belongs to (e.g., `'author'`, `'book'`).
-     * When set, the tool becomes a method on the auto-generated class.
-     * Omit for global tools (standalone exported functions).
+     * The class this effect belongs to (e.g., `'author'`, `'book'`).
+     * When set, the effect becomes a method on the auto-generated class.
+     * Omit for global effects (standalone exported functions).
      */
     className?: string;
     /**
@@ -318,8 +340,9 @@ interface ToolSchema {
      */
     static?: boolean;
 }
+type EffectSchema = ToolSchema;
 /**
- * Tool with handler — what users provide to `publishTools()`.
+ * Effect with handler — what users provide to `registerEffect()`.
  *
  * - **Instance methods** (`className` set, `static` omitted):
  *   handler receives `(objectId: string, params: any)`
@@ -331,8 +354,9 @@ interface ToolSchema {
 interface ToolWithHandler extends ToolSchema {
     handler: ToolHandler | InstanceToolHandler;
 }
+type EffectWithHandler = ToolWithHandler;
 /**
- * Result from publishing tools
+ * Result from publishing or synchronizing effects
  */
 interface PublishToolsResult {
     accepted: boolean;
@@ -342,6 +366,7 @@ interface PublishToolsResult {
         reason: string;
     }>;
 }
+type PublishEffectsResult = PublishToolsResult;
 /**
  * Domain state response
  */
@@ -356,39 +381,48 @@ interface DomainState {
     [key: string]: unknown;
 }
 /**
- * Information about a published tool
+ * Information about a live or declared effect
  */
 interface ToolInfo {
-    /** Unique name of the tool */
+    effectKey?: string;
+    /** Unique name of the effect */
     name: string;
-    /** Description of what the tool does */
+    /** Description of what the effect does */
     description?: string;
-    /** JSON Schema for tool input */
+    /** JSON Schema for effect input */
     inputSchema?: Record<string, unknown>;
-    /** JSON Schema for tool output */
+    /** JSON Schema for effect output */
     outputSchema?: Record<string, unknown>;
-    /** Client ID that published this tool (absent for domain-only entries) */
+    /** Client ID that published this effect (absent for domain-only entries) */
     clientId?: string;
-    /** Whether the tool is ready for use (has a registered handler) */
+    /** Whether the effect is ready for use (has a registered handler) */
     ready: boolean;
-    /** Timestamp when the tool was published */
+    /** Timestamp when the effect was published */
     publishedAt?: number;
-    /** Class this tool belongs to (instance/static method) */
+    /** Class this effect belongs to (instance/static method) */
     className?: string;
     /** Whether this is a static method */
     static?: boolean;
 }
+interface EffectInfo extends ToolInfo {
+}
 /**
- * Event data when the list of available tools changes
+ * Event data when the list of available effects changes
  */
 interface ToolsChangedEvent {
-    /** The current list of all available tools */
+    /** The current list of all available effects */
     tools: ToolInfo[];
-    /** Names of tools that were added or updated */
+    /** Names of effects that were added or updated */
     added: string[];
-    /** Names of tools that were removed */
+    /** Names of effects that were removed */
     removed: string[];
 }
+interface EffectsChangedEvent extends ToolsChangedEvent {
+    /** The current list of all available effects */
+    effects: EffectInfo[];
+}
+type EffectHandler = ToolHandler;
+type InstanceEffectHandler = InstanceToolHandler;
 type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
 /**
  * Result from submitting a job
@@ -600,6 +634,24 @@ interface ManifestRelationshipDef {
     /** Whether the right side is a collection */
     rightIsMany: boolean;
 }
+interface ManifestEffectSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+    description?: string;
+    [key: string]: unknown;
+}
+interface ManifestEffectDeclaration {
+    name: string;
+    description?: string;
+    attachedClass?: string;
+    isStatic?: boolean;
+    inputSchema: ManifestEffectSchema;
+    outputSchema?: ManifestEffectSchema;
+    stability?: 'stable' | 'experimental' | 'deprecated';
+    tags?: string[];
+}
 /**
  * A single operation in a manifest volume
  */
@@ -616,6 +668,8 @@ interface ManifestOperation {
     has?: Record<string, ManifestPropertySpec>;
     /** Define a relationship between two classes */
     defineRelationship?: ManifestRelationshipDef;
+    /** Declare a build-owned effect */
+    withEffect?: ManifestEffectDeclaration;
 }
 /**
  * A volume in a manifest
@@ -669,4 +723,4 @@ interface DeleteResponse {
     deleted: boolean;
 }
 
-export type { ToolInvokeParams as $, AssignmentListResponse as A, BuildPolicy as B, ConnectOptions as C, DomainState as D, EnvironmentData as E, BuildStatus as F, GranularOptions as G, Build as H, InstanceToolHandler as I, Job as J, BuildListResponse as K, JobStatus as L, ModelRef as M, JobSubmitResult as N, Prompt as O, PublishToolsResult as P, WSDisconnectInfo as Q, RecordUserOptions as R, SandboxListResponse as S, ToolWithHandler as T, User as U, WSReconnectErrorInfo as V, WSClientOptions as W, RPCRequest as X, RPCResponse as Y, SyncMessage as Z, RPCRequestFromServer as _, ToolHandler as a, ToolResultParams as a0, ManifestPropertySpec as a1, ManifestRelationshipDef as a2, ManifestOperation as a3, ManifestImport as a4, ManifestVolume as a5, APIError as a6, ToolInfo as b, ToolsChangedEvent as c, GraphQLResult as d, DefineRelationshipOptions as e, RelationshipInfo as f, ManifestContent as g, RecordObjectOptions as h, RecordObjectResult as i, Sandbox as j, CreateSandboxData as k, DeleteResponse as l, PermissionProfile as m, CreatePermissionProfileData as n, CreateEnvironmentData as o, Subject as p, ToolSchema as q, AccessTokenProvider as r, EndpointMode as s, GranularAuth as t, PermissionRules as u, PermissionProfileListResponse as v, Assignment as w, EnvironmentListResponse as x, Manifest as y, ManifestListResponse as z };
+export type { JobSubmitResult as $, AssignmentListResponse as A, BuildPolicy as B, ConnectOptions as C, DomainState as D, EffectInfo as E, Manifest as F, GranularOptions as G, ManifestListResponse as H, InstanceToolHandler as I, Job as J, BuildStatus as K, Build as L, ModelRef as M, BuildListResponse as N, EffectHandlerContext as O, PublishToolsResult as P, EffectSchema as Q, RecordUserOptions as R, SandboxListResponse as S, ToolWithHandler as T, User as U, EffectWithHandler as V, WSClientOptions as W, PublishEffectsResult as X, EffectHandler as Y, InstanceEffectHandler as Z, JobStatus as _, ToolHandler as a, Prompt as a0, WSDisconnectInfo as a1, WSReconnectErrorInfo as a2, RPCRequest as a3, RPCResponse as a4, SyncMessage as a5, RPCRequestFromServer as a6, ToolInvokeParams as a7, ToolResultParams as a8, ManifestPropertySpec as a9, ManifestRelationshipDef as aa, ManifestEffectSchema as ab, ManifestEffectDeclaration as ac, ManifestOperation as ad, ManifestImport as ae, ManifestVolume as af, APIError as ag, ToolInfo as b, EffectsChangedEvent as c, ToolsChangedEvent as d, EnvironmentData as e, GraphQLResult as f, DefineRelationshipOptions as g, RelationshipInfo as h, ManifestContent as i, RecordObjectOptions as j, RecordObjectResult as k, Sandbox as l, CreateSandboxData as m, DeleteResponse as n, PermissionProfile as o, CreatePermissionProfileData as p, CreateEnvironmentData as q, Subject as r, ToolSchema as s, AccessTokenProvider as t, EndpointMode as u, GranularAuth as v, PermissionRules as w, PermissionProfileListResponse as x, Assignment as y, EnvironmentListResponse as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granular-software/sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "TypeScript SDK and CLI for Granular - define, build, and deploy AI sandboxes",
   "main": "dist/index.js",
   "module": "dist/index.mjs",