@granular-software/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,616 @@
+import * as Automerge from '@automerge/automerge';
+import { Doc } from '@automerge/automerge';
+import { W as WSClientOptions, T as ToolWithHandler, P as PublishToolsResult, J as Job, a as ToolHandler, I as InstanceToolHandler, D as DomainState, G as GranularOptions, R as RecordUserOptions, U as User, C as ConnectOptions, E as EnvironmentData, b as GraphQLResult, c as DefineRelationshipOptions, d as RelationshipInfo, M as ModelRef, e as ManifestContent, f as RecordObjectOptions, g as RecordObjectResult, S as SandboxListResponse, h as Sandbox, i as CreateSandboxData, j as DeleteResponse, k as PermissionProfile, l as CreatePermissionProfileData, m as CreateEnvironmentData, n as Subject, A as AssignmentListResponse } from './types-D46q5WTh.js';
+export { $ as APIError, r as Assignment, w as Build, x as BuildListResponse, B as BuildPolicy, v as BuildStatus, s as EnvironmentListResponse, y as JobStatus, z as JobSubmitResult, t as Manifest, Z as ManifestImport, u as ManifestListResponse, Y as ManifestOperation, V as ManifestPropertySpec, X as ManifestRelationshipDef, _ as ManifestVolume, q as PermissionProfileListResponse, p as PermissionRules, F as Prompt, H as RPCRequest, N as RPCRequestFromServer, K as RPCResponse, L as SyncMessage, O as ToolInvokeParams, Q as ToolResultParams, o as ToolSchema } from './types-D46q5WTh.js';
+
+declare class WSClient {
+    private ws;
+    private url;
+    private sessionId;
+    private token;
+    private messageQueue;
+    private syncHandlers;
+    private rpcHandlers;
+    private eventHandlers;
+    private nextRpcId;
+    doc: Automerge.Doc<Record<string, unknown>>;
+    private syncState;
+    private reconnectTimer;
+    private isExplicitlyDisconnected;
+    constructor(options: WSClientOptions);
+    /**
+     * Connect to the WebSocket server
+     * @returns {Promise<void>} Resolves when connection is open
+     */
+    connect(): Promise<void>;
+    private handleDisconnect;
+    private handleMessage;
+    /**
+     * Make an RPC call to the server
+     * @param {string} method - RPC method name
+     * @param {unknown} params - Request parameters
+     * @returns {Promise<unknown>} Response result
+     * @throws {Error} If connection is closed or timeout occurs
+     */
+    call(method: string, params: unknown): Promise<unknown>;
+    private handleIncomingRpc;
+    /**
+     * Subscribe to client events
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler
+     */
+    on(event: string, handler: (params: unknown) => void): void;
+    /**
+     * Register an RPC handler for incoming server requests
+     * @param {string} method - RPC method name
+     * @param {Function} handler - Handler function
+     */
+    registerRpcHandler(method: string, handler: (params: unknown) => Promise<unknown>): void;
+    /**
+     * Unsubscribe from client events
+     * @param {string} event - Event name
+     * @param {Function} handler - Handler to remove
+     */
+    off(event: string, handler: (params: unknown) => void): void;
+    /**
+     * Emit an event locally
+     * @param {string} event - Event name
+     * @param params - Event data
+     */
+    emit(event: string, params: unknown): void;
+    /**
+     * Disconnect the WebSocket and clear state
+     */
+    disconnect(): void;
+}
+
+declare class Session {
+    protected client: WSClient;
+    private clientId;
+    private jobsMap;
+    private eventListeners;
+    private toolHandlers;
+    /** Tracks which tools are instance methods (className set, not static) */
+    private instanceTools;
+    private currentDomainRevision;
+    constructor(client: WSClient, clientId?: string);
+    get document(): Doc<Record<string, unknown>>;
+    get domainRevision(): string | null;
+    /**
+     * Make a raw RPC call to the session's Durable Object.
+     *
+     * Use this when you need to call an RPC method that doesn't have a
+     * dedicated wrapper method on the Session/Environment class.
+     *
+     * @param method - RPC method name (e.g. 'domain.fetchPackagePart')
+     * @param params - Request parameters
+     * @returns The raw RPC response
+     *
+     * @example
+     * ```typescript
+     * const result = await env.rpc('domain.fetchPackagePart', {
+     *   moduleSpecifier: '@sandbox/domain',
+     *   part: 'types',
+     * });
+     * ```
+     */
+    rpc<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Send client hello to establish the session
+     */
+    hello(): Promise<{
+        ok: boolean;
+        environmentId?: string;
+        docId?: string;
+    }>;
+    /**
+     * Publish tools to the sandbox and register handlers for reverse-RPC.
+     *
+     * Tools can be:
+     * - **Instance methods**: set `className` (handler receives `(objectId, params)`)
+     * - **Static methods**: set `className` + `static: true` (handler receives `(params)`)
+     * - **Global tools**: omit `className` (handler receives `(params)`)
+     *
+     * Both `inputSchema` and `outputSchema` accept JSON Schema objects. The
+     * `outputSchema` drives the return type in the auto-generated TypeScript
+     * class declarations that sandbox code imports from `./sandbox-tools`.
+     *
+     * This method:
+     * 1. Extracts tool schemas (including `outputSchema`) from the provided tools
+     * 2. Publishes them via `client.publishRawToolCatalog` RPC
+     * 3. Registers handlers locally for `tool.invoke` RPC calls
+     * 4. Returns the `domainRevision` needed for job submission
+     *
+     * @param tools - Array of tools with handlers
+     * @param revision - Optional revision string (default: "1.0.0")
+     * @returns PublishToolsResult with domainRevision
+     *
+     * @example
+     * ```typescript
+     * await env.publishTools([
+     *   {
+     *     name: 'get_bio',
+     *     description: 'Get biography of an author',
+     *     className: 'author',
+     *     inputSchema:  { type: 'object', properties: { detailed: { type: 'boolean' } } },
+     *     outputSchema: { type: 'object', properties: { bio: { type: 'string' } }, required: ['bio'] },
+     *     handler: async (id, params) => ({ bio: `Bio of ${id}` }),
+     *   },
+     * ]);
+     * ```
+     */
+    publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
+    /**
+     * Submit a job to execute code in the sandbox.
+     *
+     * The code can import typed classes from `./sandbox-tools`:
+     * ```typescript
+     * import { Author, Book, global_search } from './sandbox-tools';
+     *
+     * const tolkien = await Author.find({ id: 'tolkien' });
+     * const bio = await tolkien.get_bio({ detailed: true });
+     * const books = await tolkien.get_books();
+     * ```
+     *
+     * Tool calls (instance methods, static methods, global functions) trigger
+     * `tool.invoke` RPC back to this client, where the registered handlers
+     * execute locally and return the result to the sandbox.
+     */
+    submitJob(code: string, domainRevision?: string): Promise<Job>;
+    /**
+     * Register a handler for a specific tool.
+     * @param isInstance - If true, handler will receive (id, params) for instance method dispatch.
+     */
+    registerToolHandler(name: string, handler: ToolHandler | InstanceToolHandler, isInstance?: boolean): void;
+    /**
+     * Respond to a prompt request from the sandbox
+     */
+    answerPrompt(promptId: string, answer: unknown): Promise<void>;
+    /**
+     * Get the current domain state and available tools
+     */
+    getDomain(): Promise<DomainState>;
+    /**
+     * Get auto-generated TypeScript class declarations for the current domain.
+     *
+     * Returns typed declarations including:
+     * - Classes with readonly properties (from manifest)
+     * - `static find(query: { id: string })` for each class
+     * - Instance methods with typed input/output (from `publishTools` with `className`)
+     * - Static methods (from `publishTools` with `className` + `static: true`)
+     * - Relationship accessors (`get_books()`, `get_author()`, etc.)
+     * - Global tool functions (from `publishTools` without `className`)
+     *
+     * Pass this documentation to LLMs so they can write correct typed code
+     * that imports from `./sandbox-tools`.
+     *
+     * Falls back to generating markdown docs from the domain summary if
+     * the synthesis server is unavailable.
+     */
+    getDomainDocumentation(): Promise<string>;
+    /**
+     * Generate markdown documentation from the domain summary.
+     * Class-aware: groups tools by class with property/relationship info.
+     */
+    private generateFallbackDocs;
+    /**
+     * Close the session and disconnect from the sandbox
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Subscribe to session events
+     */
+    on(event: string, handler: (data: unknown) => void): void;
+    /**
+     * Unsubscribe from session events
+     */
+    off(event: string, handler: (data: unknown) => void): void;
+    private setupToolInvokeHandler;
+    private setupEventHandlers;
+    private emit;
+}
+
+/**
+ * Environment represents a connected session to a sandbox for a specific user.
+ *
+ * After connecting, you can:
+ * 1. Define your domain ontology via `applyManifest()` (classes, properties, relationships)
+ * 2. Record object instances via `recordObject()` (with fields and relationship attachments)
+ * 3. Publish tools via `publishTools()` (instance methods, static methods, global tools — with typed I/O)
+ * 4. Submit jobs via `submitJob()` that import auto-generated typed classes from `./sandbox-tools`
+ * 5. Execute GraphQL queries via `graphql()` (authenticated automatically)
+ *
+ * Tool calls from the sandbox automatically invoke your handlers via reverse-RPC.
+ *
+ * Object IDs are unique per class. Internally, the graph path is `{className}_{id}`
+ * (e.g., `author_tolkien`). Use `Environment.toGraphPath()` and
+ * `Environment.extractIdFromGraphPath()` for conversions.
+ */
+declare class Environment extends Session {
+    private envData;
+    private _apiKey;
+    private _apiEndpoint;
+    constructor(client: WSClient, envData: EnvironmentData, clientId: string, apiKey: string, apiEndpoint: string);
+    /** The environment ID */
+    get environmentId(): string;
+    /** The sandbox ID */
+    get sandboxId(): string;
+    /** The subject ID */
+    get subjectId(): string;
+    /** The permission profile ID */
+    get permissionProfileId(): string;
+    /** The GraphQL API endpoint URL */
+    get apiEndpoint(): string;
+    /**
+     * Convert a class name + real-world ID into a unique graph path.
+     *
+     * Two objects of *different* classes may share the same real-world ID,
+     * so the graph path must incorporate the class to guarantee uniqueness.
+     *
+     * Format: `{className}_{id}` — deterministic, human-readable.
+     *
+     * **Convention**: class names should be simple identifiers without
+     * underscores (e.g. `author`, `book`).  This ensures the prefix is
+     * unambiguously parseable by `extractIdFromGraphPath`.
+     */
+    static toGraphPath(className: string, id: string): string;
+    /**
+     * Extract the real-world ID from a graph path, given the class name.
+     *
+     * Strips the `{className}_` prefix. Returns the raw path if the
+     * expected prefix is not found.
+     */
+    static extractIdFromGraphPath(graphPath: string, className: string): string;
+    /**
+     * Execute a GraphQL query against the environment's graph.
+     *
+     * The query uses the Granular graph query language (based on Cypher/GraphQL).
+     * Authentication is handled automatically using the SDK's API key.
+     *
+     * @param query - The GraphQL query string
+     * @param variables - Optional variables for the query
+     * @returns The query result data
+     *
+     * @example
+     * ```typescript
+     * // Read the workspace
+     * const result = await env.graphql(
+     *   `query { model(path: "workspace") { path label submodels { path label } } }`
+     * );
+     * console.log(result.data);
+     *
+     * // Create a model
+     * const created = await env.graphql(
+     *   `mutation { at(path: "workspace") { create_submodel(subpath: "my_node", label: "My Node", prototype: "Model") { model { path label } } } }`
+     * );
+     * ```
+     */
+    graphql<T = any>(query: string, variables?: Record<string, any>): Promise<GraphQLResult<T>>;
+    /**
+     * Define a relationship between two model types.
+     *
+     * Creates both submodels (if they don't exist) and links them with
+     * a RelationshipDef node that encodes cardinality.
+     *
+     * @example
+     * ```typescript
+     * // Author has many Books, Book has one Author
+     * const rel = await env.defineRelationship({
+     *   model: 'author',
+     *   localSubmodel: 'books',
+     *   localIsMany: true,
+     *   foreignModel: 'book',
+     *   foreignSubmodel: 'author',
+     *   foreignIsMany: false,
+     * });
+     * console.log(rel.relationship_kind); // "one_to_many"
+     * ```
+     */
+    defineRelationship(options: DefineRelationshipOptions): Promise<RelationshipInfo>;
+    /**
+     * Get all relationships for a model type.
+     *
+     * @param modelPath - The model type path (e.g., "author")
+     * @returns Array of relationships from this model's perspective
+     *
+     * @example
+     * ```typescript
+     * const rels = await env.getRelationships('author');
+     * for (const rel of rels) {
+     *   console.log(`${rel.local_submodel.path} -> ${rel.foreign_model.path} (${rel.relationship_kind})`);
+     * }
+     * ```
+     */
+    getRelationships(modelPath: string): Promise<RelationshipInfo[]>;
+    /**
+     * Attach a target model to a relationship submodel.
+     *
+     * Handles cardinality automatically:
+     * - "One" side: sets/replaces the reference
+     * - "Many" side: adds the target to the collection
+     *
+     * If the target model doesn't exist, it's created as an instance of the foreign type.
+     * Bidirectional sync is automatic.
+     *
+     * @param modelPath - The model instance path (e.g., "tolkien")
+     * @param submodelPath - The relationship submodel (e.g., "books")
+     * @param targetPath - The target model to attach (e.g., "lord_of_the_rings")
+     *
+     * @example
+     * ```typescript
+     * // Attach a book to an author (many side)
+     * await env.attach('tolkien', 'books', 'lord_of_the_rings');
+     * // This also automatically sets lord_of_the_rings:author -> tolkien
+     * ```
+     */
+    attach(modelPath: string, submodelPath: string, targetPath: string): Promise<void>;
+    /**
+     * Detach a target model from a relationship submodel.
+     *
+     * Handles bidirectional cleanup automatically.
+     *
+     * @param modelPath - The model instance path
+     * @param submodelPath - The relationship submodel
+     * @param targetPath - The target to detach (optional for "one" side; omit on "many" side to detach all)
+     *
+     * @example
+     * ```typescript
+     * // Detach a specific book
+     * await env.detach('tolkien', 'books', 'lord_of_the_rings');
+     *
+     * // Detach all books
+     * await env.detach('tolkien', 'books');
+     * ```
+     */
+    detach(modelPath: string, submodelPath: string, targetPath?: string): Promise<void>;
+    /**
+     * List all related models through a relationship submodel.
+     *
+     * @param modelPath - The model instance path
+     * @param submodelPath - The relationship submodel
+     * @returns Array of related model references
+     *
+     * @example
+     * ```typescript
+     * const books = await env.listRelated('tolkien', 'books');
+     * console.log(books); // [{ path: "lord_of_the_rings", label: "Lord of the Rings" }, ...]
+     * ```
+     */
+    listRelated(modelPath: string, submodelPath: string): Promise<ModelRef[]>;
+    /**
+     * Apply a manifest to the current environment's graph.
+     *
+     * Translates each manifest operation into GraphQL mutations and executes them
+     * in order. This is the core mechanism for creating classes, fields, and
+     * relationships from a declarative manifest.
+     *
+     * @param manifest - The manifest content to apply
+     * @returns Summary of applied operations
+     *
+     * @example
+     * ```typescript
+     * await environment.applyManifest({
+     *   schemaVersion: 2,
+     *   name: 'my-app',
+     *   volumes: [{
+     *     name: 'schema',
+     *     scope: 'sandbox',
+     *     operations: [
+     *       { create: 'author', extends: 'class', has: { name: { type: 'string' } } },
+     *       { create: 'book', extends: 'class', has: { title: { type: 'string' } } },
+     *       { defineRelationship: {
+     *         left: 'author', right: 'book',
+     *         leftSubmodel: 'books', rightSubmodel: 'author',
+     *         leftIsMany: true, rightIsMany: false,
+     *       }},
+     *     ],
+     *   }],
+     * });
+     * ```
+     */
+    applyManifest(manifest: ManifestContent): Promise<{
+        applied: number;
+        errors: string[];
+    }>;
+    /**
+     * Resolve an alias reference like "@std/class" → "class"
+     * Strips the alias prefix, returning the bare model path.
+     */
+    private _resolveAlias;
+    /**
+     * Apply a single manifest operation via GraphQL
+     */
+    private _applyOperation;
+    /**
+     * Apply field definitions (has) to a model via GraphQL
+     */
+    private _applyFields;
+    /**
+     * Create or update an instance of a class in the graph.
+     *
+     * Uses `instantiate` under the hood, which has find-or-create semantics:
+     * if an instance with the given `id` already exists for the class it is
+     * returned; otherwise a new instance is created.  Fields are then set
+     * (overwriting previous values) and relationships are attached.
+     *
+     * The graph path is derived as `{className}_{id}` to ensure uniqueness
+     * across classes (two objects of different classes may share the same
+     * real-world ID).  Relationship targets are also resolved automatically
+     * using the foreign class from the relationship definition.
+     *
+     * @param options - The object specification
+     * @returns The graph path, real-world ID, and creation status
+     *
+     * @example
+     * ```typescript
+     * // Create an author with fields
+     * const result = await env.recordObject({
+     *   className: 'author',
+     *   id: 'tolkien',
+     *   label: 'J.R.R. Tolkien',
+     *   fields: { name: 'J.R.R. Tolkien', birth_year: 1892 },
+     *   relationships: { books: ['lotr', 'silmarillion'] },
+     * });
+     * // result.path → 'author_tolkien'  (internal graph path)
+     * // result.id   → 'tolkien'         (real-world ID)
+     * // result.created → true
+     * ```
+     */
+    recordObject(options: RecordObjectOptions): Promise<RecordObjectResult>;
+    /**
+     * Convenience method: publish tools and get back wrapped result.
+     * This is the main entry point for setting up tools.
+     *
+     * @example
+     * ```typescript
+     * const tools = [
+     *   {
+     *     name: 'get_weather',
+     *     description: 'Get weather for a city',
+     *     inputSchema: { type: 'object', properties: { city: { type: 'string' } } },
+     *     handler: async ({ city }) => ({ temp: 22 }),
+     *   },
+     * ];
+     *
+     * const { domainRevision } = await environment.publishTools(tools);
+     *
+     * // Now submit jobs that use those tools
+     * const job = await environment.submitJob(`
+     *   import { Author } from './sandbox-tools';
+     *   const weather = await Author.get_weather({ city: 'Paris' });
+     *   return weather;
+     * `);
+     *
+     * const result = await job.result;
+     * ```
+     */
+    publishTools(tools: ToolWithHandler[], revision?: string): Promise<PublishToolsResult>;
+}
+declare class Granular {
+    private apiKey;
+    private apiUrl;
+    private httpUrl;
+    /**
+     * Create a new Granular client
+     * @param options - Client configuration
+     */
+    constructor(options: GranularOptions);
+    /**
+     * Records/upserts a user and prepares them for sandbox connections
+     *
+     * @param options - User options
+     * @returns The user object to pass to connect()
+     *
+     * @example
+     * ```typescript
+     * const user = await granular.recordUser({
+     *   userId: 'user_123',
+     *   name: 'John Doe',
+     *   permissions: ['agent'],
+     * });
+     * ```
+     */
+    recordUser(options: RecordUserOptions): Promise<User>;
+    /**
+     * Connect to a sandbox and establish a real-time environment session.
+     *
+     * After connecting, use `environment.publishTools()` to register tools,
+     * then `environment.submitJob()` to execute code that uses those tools.
+     *
+     * @param options - Connection options
+     * @returns An active environment session
+     *
+     * @example
+     * ```typescript
+     * const user = await granular.recordUser({
+     *   userId: 'user_123',
+     *   permissions: ['agent'],
+     * });
+     *
+     * const environment = await granular.connect({
+     *   sandbox: 'my-sandbox',
+     *   user,
+     * });
+     *
+     * // Publish tools
+     * await environment.publishTools([
+     *   { name: 'greet', description: 'Say hello', inputSchema: {}, handler: async () => 'Hello!' },
+     * ]);
+     *
+     * // Submit job
+     * const job = await environment.submitJob(`
+     *   import { tools } from './sandbox-tools';
+     *   return await tools.greet({});
+     * `);
+     *
+     * console.log(await job.result); // 'Hello!'
+     * ```
+     */
+    connect(options: ConnectOptions): Promise<Environment>;
+    /**
+     * Find a sandbox by name or create it if it doesn't exist
+     */
+    private findOrCreateSandbox;
+    /**
+     * Ensure a permission profile exists for a sandbox, creating it if needed.
+     * If profileName matches an existing profile name, returns its ID.
+     * Otherwise, creates a new profile with default allow-all rules.
+     */
+    private ensurePermissionProfile;
+    /**
+     * Ensure an assignment exists for a subject in a sandbox with a permission profile
+     */
+    private ensureAssignment;
+    /**
+     * Sandbox management API
+     */
+    get sandboxes(): {
+        list: () => Promise<SandboxListResponse>;
+        get: (id: string) => Promise<Sandbox>;
+        create: (data: CreateSandboxData) => Promise<Sandbox>;
+        update: (id: string, data: Partial<CreateSandboxData>) => Promise<Sandbox>;
+        delete: (id: string) => Promise<DeleteResponse>;
+    };
+    /**
+     * Permission Profile management for sandboxes
+     */
+    get permissionProfiles(): {
+        list: (sandboxId: string) => Promise<PermissionProfile[]>;
+        get: (sandboxId: string, profileId: string) => Promise<PermissionProfile>;
+        create: (sandboxId: string, data: CreatePermissionProfileData) => Promise<PermissionProfile>;
+        delete: (sandboxId: string, profileId: string) => Promise<DeleteResponse>;
+    };
+    /**
+     * Environment management
+     */
+    get environments(): {
+        list: (sandboxId: string) => Promise<EnvironmentData[]>;
+        get: (environmentId: string) => Promise<EnvironmentData>;
+        create: (sandboxId: string, data: CreateEnvironmentData) => Promise<EnvironmentData>;
+        delete: (environmentId: string) => Promise<DeleteResponse>;
+    };
+    /**
+     * Subject management
+     */
+    get subjects(): {
+        get: (subjectId: string) => Promise<Subject>;
+        listAssignments: (subjectId: string) => Promise<AssignmentListResponse>;
+    };
+    /**
+     * @deprecated Use recordUser() instead
+     */
+    get users(): {
+        create: (data: {
+            id: string;
+            name?: string;
+            email?: string;
+        }) => Promise<Subject>;
+        get: (id: string) => Promise<Subject>;
+    };
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+}
+
+export { AssignmentListResponse, ConnectOptions, CreateEnvironmentData, CreatePermissionProfileData, CreateSandboxData, DefineRelationshipOptions, DeleteResponse, DomainState, Environment, EnvironmentData, Granular, GranularOptions, GraphQLResult, InstanceToolHandler, Job, ManifestContent, ModelRef, PermissionProfile, PublishToolsResult, RecordObjectOptions, RecordObjectResult, RecordUserOptions, RelationshipInfo, Sandbox, SandboxListResponse, Session, Subject, ToolHandler, ToolWithHandler, User, WSClient, WSClientOptions };