@granular-software/sdk 0.1.0

package/dist/types-D46q5WTh.d.ts

@@ -0,0 +1,595 @@
+/**
+ * @module @granular-software/sdk/types
+ * Type definitions for the Granular SDK
+ */
+/**
+ * Configuration for the Granular client
+ */
+interface GranularOptions {
+    /** Your Granular API key */
+    apiKey: string;
+    /** Optional API URL (for on-prem or testing) */
+    apiUrl?: string;
+}
+/**
+ * A user/subject object returned from recordUser()
+ */
+interface User {
+    /** Internal subject ID */
+    subjectId: string;
+    /** External identity ID (e.g. Auth0 ID) */
+    identityId: string;
+    /** User's display name */
+    name?: string;
+    /** User's email */
+    email?: string;
+    /** Permission profile IDs to be assigned when connecting */
+    permissions: string[];
+}
+/**
+ * Options for recording a user
+ */
+interface RecordUserOptions {
+    /** External user/identity ID (e.g. your Auth0 or database user ID) */
+    userId: string;
+    /** User's display name */
+    name?: string;
+    /** User's email */
+    email?: string;
+    /** Permission profile IDs to assign when connecting to sandboxes */
+    permissions?: string[];
+}
+/**
+ * Subject as returned from the API
+ */
+interface Subject {
+    subjectId: string;
+    tenantId: string;
+    identityId: string;
+    email?: string | null;
+    name?: string | null;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Options for connecting to a sandbox
+ */
+interface ConnectOptions {
+    /** The sandbox name or ID to connect to */
+    sandbox: string;
+    /** The user to connect as (from recordUser()) */
+    user: User;
+}
+/**
+ * A sandbox container
+ */
+interface Sandbox {
+    sandboxId: string;
+    tenantId: string;
+    name: string;
+    description?: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating a new sandbox
+ */
+interface CreateSandboxData {
+    name: string;
+    description?: string;
+}
+/**
+ * List response for sandboxes
+ */
+interface SandboxListResponse {
+    items: Sandbox[];
+}
+/**
+ * Rules defining what tools and resources are allowed/denied
+ */
+interface PermissionRules {
+    /** Tool access rules */
+    tools?: {
+        /** Patterns for allowed tools (e.g. ["*"] for all, ["read_*"] for prefix match) */
+        allow?: string[];
+        /** Patterns for denied tools */
+        deny?: string[];
+    };
+    /** Resource access rules */
+    resources?: {
+        /** Patterns for allowed resources */
+        allow?: string[];
+        /** Patterns for denied resources */
+        deny?: string[];
+    };
+}
+/**
+ * A permission profile defines access controls for an environment
+ */
+interface PermissionProfile {
+    permissionProfileId: string;
+    sandboxId: string;
+    name: string;
+    rules: PermissionRules;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating a new permission profile
+ */
+interface CreatePermissionProfileData {
+    name: string;
+    rules: PermissionRules;
+}
+/**
+ * List response for permission profiles
+ */
+interface PermissionProfileListResponse {
+    items: PermissionProfile[];
+}
+/**
+ * An assignment links a subject to a sandbox with a permission profile
+ */
+interface Assignment {
+    assignmentId: string;
+    tenantId: string;
+    subjectId: string;
+    sandboxId: string;
+    permissionProfileId: string;
+    createdAt: number;
+    createdBy?: string | null;
+}
+/**
+ * List response for assignments
+ */
+interface AssignmentListResponse {
+    items: Assignment[];
+}
+/**
+ * Build policy for environments
+ */
+interface BuildPolicy {
+    mode: 'current' | 'pinned';
+    buildId?: string;
+}
+/**
+ * An environment links a user (subject) to a sandbox with specific permissions
+ */
+interface EnvironmentData {
+    environmentId: string;
+    sandboxId: string;
+    buildId: string;
+    subjectId: string;
+    permissionProfileId: string;
+    buildPolicy: BuildPolicy;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating a new environment
+ */
+interface CreateEnvironmentData {
+    /** The user/subject ID to create the environment for */
+    subjectId: string;
+    /** The permission profile to apply (optional - uses assignment if not specified) */
+    permissionProfileId?: string | null;
+    /** Build policy (defaults to current build) */
+    buildPolicy?: BuildPolicy;
+}
+/**
+ * List response for environments
+ */
+interface EnvironmentListResponse {
+    items: EnvironmentData[];
+}
+/**
+ * A manifest describes the structure and behavior of a sandbox
+ */
+interface Manifest {
+    manifestId: string;
+    sandboxId: string;
+    version: string;
+    digest: string;
+    content?: Record<string, unknown>;
+    createdAt: number;
+    locked?: boolean;
+}
+/**
+ * List response for manifests
+ */
+interface ManifestListResponse {
+    items: Manifest[];
+}
+type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
+/**
+ * A build represents a compiled version of a manifest
+ */
+interface Build {
+    buildId: string;
+    sandboxId: string;
+    manifestId: string;
+    status: BuildStatus;
+    graphBinaryId?: string | null;
+    logsUri?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    isCurrent?: boolean;
+}
+/**
+ * List response for builds
+ */
+interface BuildListResponse {
+    items: Build[];
+}
+/**
+ * Tool handler for static/global tools: receives (params)
+ */
+type ToolHandler = (input: any) => Promise<unknown>;
+/**
+ * Tool handler for instance methods: receives (objectId, params)
+ */
+type InstanceToolHandler = (id: string, input: any) => Promise<unknown>;
+/**
+ * Tool schema for publishing to the server.
+ *
+ * Tools come in three flavours:
+ *
+ * 1. **Instance methods** — set `className`, omit `static`.
+ *    In the sandbox: `tolkien.get_bio({ detailed: true })`
+ *    Handler signature: `(objectId: string, params: any) => any`
+ *
+ * 2. **Static methods** — set `className` + `static: true`.
+ *    In the sandbox: `Author.search({ query: 'tolkien' })`
+ *    Handler signature: `(params: any) => any`
+ *
+ * 3. **Global tools** — omit `className`.
+ *    In the sandbox: `global_search({ query: 'rings' })`
+ *    Handler signature: `(params: any) => any`
+ *
+ * Both `inputSchema` and `outputSchema` accept JSON Schema objects.
+ * The `outputSchema` drives the return type in the auto-generated
+ * TypeScript declarations that sandbox code imports from `./sandbox-tools`.
+ */
+interface ToolSchema {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's input parameters */
+    inputSchema: Record<string, unknown>;
+    /**
+     * JSON Schema for the tool's return value.
+     * Used to generate typed return types in the sandbox TypeScript declarations.
+     *
+     * @example
+     * ```typescript
+     * outputSchema: {
+     *   type: 'object',
+     *   properties: {
+     *     bio: { type: 'string', description: 'The biography text' },
+     *     source: { type: 'string', description: 'Source of the bio' },
+     *   },
+     *   required: ['bio'],
+     * }
+     * // Generates: Promise<{ bio: string; source?: string }>
+     * ```
+     */
+    outputSchema?: Record<string, unknown>;
+    stability?: 'stable' | 'experimental' | 'deprecated';
+    provenance?: {
+        source: 'mcp' | 'custom';
+    };
+    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).
+     */
+    className?: string;
+    /**
+     * If `true`, this is a static/class-level method (no object ID required).
+     * If `false` or omitted and `className` is set, this is an instance method
+     * that operates on a specific object (the object's real-world ID is
+     * passed as the first argument to the handler).
+     */
+    static?: boolean;
+}
+/**
+ * Tool with handler — what users provide to `publishTools()`.
+ *
+ * - **Instance methods** (`className` set, `static` omitted):
+ *   handler receives `(objectId: string, params: any)`
+ * - **Static methods** (`className` set, `static: true`):
+ *   handler receives `(params: any)`
+ * - **Global tools** (no `className`):
+ *   handler receives `(params: any)`
+ */
+interface ToolWithHandler extends ToolSchema {
+    handler: ToolHandler | InstanceToolHandler;
+}
+/**
+ * Result from publishing tools
+ */
+interface PublishToolsResult {
+    accepted: boolean;
+    domainRevision: string;
+    rejected?: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+/**
+ * Domain state response
+ */
+interface DomainState {
+    activeDomainRevision?: string;
+    tools?: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+    }>;
+    [key: string]: unknown;
+}
+type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+/**
+ * Result from submitting a job
+ */
+interface JobSubmitResult {
+    jobId: string;
+}
+/**
+ * Represents a job executed in the sandbox
+ */
+interface Job {
+    /** Unique Job ID */
+    id: string;
+    /** Current status of the job */
+    status: JobStatus;
+    /** Promise that resolves with the job result */
+    result: Promise<unknown>;
+    /** Subscribe to job events */
+    on(event: string, handler: (data: unknown) => void): void;
+}
+interface Prompt {
+    id: string;
+    type: 'confirm' | 'choice' | 'input';
+    title: string;
+    message: string;
+    options?: string[];
+    defaultValue?: unknown;
+}
+interface WSClientOptions {
+    url: string;
+    sessionId: string;
+    token: string;
+}
+interface RPCRequest {
+    type: 'rpc';
+    method: string;
+    params: unknown;
+    id: string;
+}
+interface RPCResponse {
+    type: 'rpc_result' | 'rpc_error';
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface SyncMessage {
+    type: 'sync';
+    message?: string | number[] | Uint8Array;
+    data?: number[];
+}
+interface RPCRequestFromServer {
+    type: 'rpc';
+    method: string;
+    params: unknown;
+    id: string;
+}
+interface ToolInvokeParams {
+    callId: string;
+    toolName: string;
+    input: unknown;
+}
+interface ToolResultParams {
+    callId: string;
+    result?: unknown;
+    error?: string | {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * A model reference as returned from relationship queries
+ */
+interface ModelRef {
+    path: string;
+    label?: string;
+}
+/**
+ * Relationship info as returned from the GraphQL API.
+ * Represents a typed, bidirectional relationship between two model types,
+ * seen from one model's perspective.
+ */
+interface RelationshipInfo {
+    /** Unique name of this relationship definition */
+    name: string;
+    /** The submodel on this model that holds the relationship */
+    local_submodel: ModelRef;
+    /** Whether this side is a "many" collection */
+    local_is_many: boolean;
+    /** The submodel on the foreign model */
+    foreign_submodel: ModelRef;
+    /** Whether the foreign side is a "many" collection */
+    foreign_is_many: boolean;
+    /** The foreign model type */
+    foreign_model: ModelRef;
+    /** Computed relationship kind: "one_to_one" | "one_to_many" | "many_to_one" | "many_to_many" */
+    relationship_kind: 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
+}
+/**
+ * Options for defining a relationship between two model types
+ */
+interface DefineRelationshipOptions {
+    /** The model to define the relationship on (the "left" / "local" type) */
+    model: string;
+    /** The submodel name on the local model (e.g., "books") */
+    localSubmodel: string;
+    /** Whether the local side is "many" */
+    localIsMany: boolean;
+    /** The foreign model type (e.g., "book") */
+    foreignModel: string;
+    /** The submodel name on the foreign model (e.g., "author") */
+    foreignSubmodel: string;
+    /** Whether the foreign side is "many" */
+    foreignIsMany: boolean;
+    /** Optional relationship name (auto-generated if omitted) */
+    name?: string;
+}
+/**
+ * Options for creating or updating a class instance in the graph.
+ *
+ * `recordObject` uses the graph's `instantiate` (find-or-create) semantics:
+ * if an instance with the given `id` already exists under the class, its
+ * fields are updated in place; otherwise a new instance is created.
+ */
+interface RecordObjectOptions {
+    /** The class to instantiate (e.g., "author") */
+    className: string;
+    /**
+     * Real-world object ID. Unique within its class, but two objects of
+     * different classes may share the same ID.  Internally the SDK derives
+     * a unique graph path as `{className}__{id}`.
+     */
+    id: string;
+    /** Optional display label (defaults to `id`) */
+    label?: string;
+    /** Scalar field values to set on the instance */
+    fields?: Record<string, string | number | boolean | null>;
+    /**
+     * Relationship attachments.
+     * Keys are relationship submodel names.  Values are real-world IDs
+     * (not graph paths) — the SDK resolves them using the foreign class
+     * derived from the relationship definition.
+     * - For a "one" side: pass a single target ID (string)
+     * - For a "many" side: pass an array of target IDs
+     */
+    relationships?: Record<string, string | string[]>;
+}
+/**
+ * Return value from `recordObject()`
+ */
+interface RecordObjectResult {
+    /** The internal graph path (e.g., "author__tolkien") */
+    path: string;
+    /** The real-world object ID as provided by the caller (e.g., "tolkien") */
+    id: string;
+    /** Whether the instance was newly created (false = updated) */
+    created: boolean;
+}
+/**
+ * Property specification in a manifest operation
+ */
+interface ManifestPropertySpec {
+    value?: string | number | boolean;
+    ref?: string;
+    instanceOf?: string;
+    create?: string;
+    has?: Record<string, ManifestPropertySpec>;
+    type?: string;
+    description?: string;
+    required?: boolean;
+}
+/**
+ * Relationship definition between two classes
+ */
+interface ManifestRelationshipDef {
+    /** Optional name (auto-generated from left_right if omitted) */
+    name?: string;
+    /** Left model path */
+    left: string;
+    /** Right model path */
+    right: string;
+    /** Submodel name on the left model */
+    leftSubmodel: string;
+    /** Submodel name on the right model */
+    rightSubmodel: string;
+    /** Whether the left side is a collection */
+    leftIsMany: boolean;
+    /** Whether the right side is a collection */
+    rightIsMany: boolean;
+}
+/**
+ * A single operation in a manifest volume
+ */
+interface ManifestOperation {
+    /** Create a new model/class */
+    create?: string;
+    /** Target an existing model for modification */
+    on?: string;
+    /** Extend from a parent class */
+    extends?: string;
+    /** Instantiate a type */
+    instanceOf?: string;
+    /** Define submodels/fields */
+    has?: Record<string, ManifestPropertySpec>;
+    /** Define a relationship between two classes */
+    defineRelationship?: ManifestRelationshipDef;
+}
+/**
+ * A volume in a manifest
+ */
+/**
+ * Import descriptor for referencing modules
+ */
+interface ManifestImport {
+    /** Alias prefix used in operations (e.g., "@std") */
+    alias: string;
+    /** Module name (e.g., "standard_modules") */
+    name: string;
+    /** Version label (e.g., "prod", "v1.2.3") */
+    label?: string;
+}
+interface ManifestVolume {
+    name: string;
+    scope: 'sandbox' | 'build' | 'user';
+    imports?: ManifestImport[];
+    operations: ManifestOperation[];
+}
+/**
+ * A manifest defines the structure of a sandbox's data model
+ */
+interface ManifestContent {
+    schemaVersion: 2;
+    name: string;
+    description?: string;
+    volumes: ManifestVolume[];
+}
+/**
+ * Result from a GraphQL query execution
+ */
+interface GraphQLResult<T = any> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        locations?: Array<{
+            line: number;
+            column: number;
+        }>;
+        path?: Array<string | number>;
+        extensions?: Record<string, any>;
+    }>;
+}
+interface APIError {
+    error: string;
+    message?: string;
+}
+interface DeleteResponse {
+    deleted: boolean;
+}
+
+export type { APIError as $, AssignmentListResponse as A, BuildPolicy as B, ConnectOptions as C, DomainState as D, EnvironmentData as E, Prompt as F, GranularOptions as G, RPCRequest as H, InstanceToolHandler as I, Job as J, RPCResponse as K, SyncMessage as L, ModelRef as M, RPCRequestFromServer as N, ToolInvokeParams as O, PublishToolsResult as P, ToolResultParams as Q, RecordUserOptions as R, SandboxListResponse as S, ToolWithHandler as T, User as U, ManifestPropertySpec as V, WSClientOptions as W, ManifestRelationshipDef as X, ManifestOperation as Y, ManifestImport as Z, ManifestVolume as _, ToolHandler as a, GraphQLResult as b, DefineRelationshipOptions as c, RelationshipInfo as d, ManifestContent as e, RecordObjectOptions as f, RecordObjectResult as g, Sandbox as h, CreateSandboxData as i, DeleteResponse as j, PermissionProfile as k, CreatePermissionProfileData as l, CreateEnvironmentData as m, Subject as n, ToolSchema as o, PermissionRules as p, PermissionProfileListResponse as q, Assignment as r, EnvironmentListResponse as s, Manifest as t, ManifestListResponse as u, BuildStatus as v, Build as w, BuildListResponse as x, JobStatus as y, JobSubmitResult as z };

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@granular-software/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Granular - wrap your existing tools and run them in secure sandboxes",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./mastra": {
+      "types": "./dist/adapters/mastra.d.ts",
+      "import": "./dist/adapters/mastra.mjs",
+      "require": "./dist/adapters/mastra.js"
+    },
+    "./langchain": {
+      "types": "./dist/adapters/langchain.d.ts",
+      "import": "./dist/adapters/langchain.mjs",
+      "require": "./dist/adapters/langchain.js"
+    },
+    "./openai": {
+      "types": "./dist/adapters/openai.d.ts",
+      "import": "./dist/adapters/openai.mjs",
+      "require": "./dist/adapters/openai.js"
+    },
+    "./anthropic": {
+      "types": "./dist/adapters/anthropic.d.ts",
+      "import": "./dist/adapters/anthropic.mjs",
+      "require": "./dist/adapters/anthropic.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "deploy": "npm run build && npm publish --access public"
+  },
+  "keywords": [
+    "granular",
+    "sdk",
+    "ai",
+    "agent",
+    "tools",
+    "sandbox",
+    "mastra",
+    "langchain",
+    "openai",
+    "anthropic"
+  ],
+  "author": "Granular Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/granular-dev/granular-sdk"
+  },
+  "dependencies": {
+    "@automerge/automerge": "^2.2.9",
+    "ws": "^8.18.2",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "zod": "3.25.76",
+    "@langchain/core": "^0.1.0",
+    "openai": "^4.0.0",
+    "@anthropic-ai/sdk": "^0.10.0"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=0.1.0",
+    "@langchain/core": ">=0.1.0",
+    "openai": ">=4.0.0",
+    "@anthropic-ai/sdk": ">=0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@mastra/core": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}