@granular-software/sdk 0.4.2 → 0.4.4

package/dist/types-C0AVRsVR.d.mts

@@ -1,726 +0,0 @@
-/**
- * @module @granular-software/sdk/types
- * Type definitions for the Granular SDK
- */
-/**
- * Configuration for the Granular client
- */
-type AccessTokenProvider = () => Promise<string | null | undefined> | string | null | undefined;
-type EndpointMode = 'auto' | 'local' | 'production';
-interface GranularOptions {
-    /** Your Granular API key (for service/CLI auth; use with GRANULAR_API_KEY) */
-    apiKey?: string;
-    /** Application/session JWT (for user-context auth; use from simulator or getAccessToken) */
-    token?: string;
-    /** Optional provider used to refresh JWT before WebSocket (re)connect attempts */
-    tokenProvider?: AccessTokenProvider;
-    /** Optional API URL (for on-prem or testing) */
-    apiUrl?: string;
-    /** Optional endpoint mode when apiUrl is not explicitly provided */
-    endpointMode?: EndpointMode;
-    /** Optional WebSocket constructor (for Node.js environments) */
-    WebSocketCtor?: any;
-    /**
-     * Optional callback invoked when a connected WebSocket closes unexpectedly.
-     * Useful for forwarding close diagnostics to monitoring (e.g., Sentry).
-     */
-    onUnexpectedClose?: (info: WSDisconnectInfo) => void;
-    /**
-     * Optional callback invoked when automatic reconnect fails.
-     * Useful to capture auth or gateway rejection causes.
-     */
-    onReconnectError?: (info: WSReconnectErrorInfo) => void;
-}
-/** Resolved auth credential: either apiKey or token must be provided */
-type GranularAuth = 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;
-    /** 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;
-}
-/**
- * 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 effects and resources are allowed or denied.
- */
-interface PermissionRules {
-    /** 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 effects (e.g. ["*"] for all, ["read_*"] for prefix match) */
-        allow?: string[];
-        /** Patterns for denied effects */
-        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[];
-}
-/**
- * Effect handler for static/global effects: receives (input, context)
- */
-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>;
-/**
- * Effect handler for instance methods: receives (objectId, input, context)
- */
-type InstanceToolHandler = (id: string, input: any, context: EffectHandlerContext) => Promise<unknown>;
-/**
- * Effect schema for declaring or registering an effect.
- *
- * Effects 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 effects** — 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 {
-    effectKey?: string;
-    name: string;
-    description: string;
-    /** JSON Schema for the effect 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 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;
-    /**
-     * 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;
-}
-type EffectSchema = ToolSchema;
-/**
- * Effect with handler — what users provide to `registerEffect()`.
- *
- * - **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;
-}
-type EffectWithHandler = ToolWithHandler;
-/**
- * Result from publishing or synchronizing effects
- */
-interface PublishToolsResult {
-    accepted: boolean;
-    domainRevision: string;
-    rejected?: Array<{
-        name: string;
-        reason: string;
-    }>;
-}
-type PublishEffectsResult = PublishToolsResult;
-/**
- * Domain state response
- */
-interface DomainState {
-    activeDomainRevision?: string;
-    tools?: Array<{
-        name: string;
-        description?: string;
-        inputSchema?: Record<string, unknown>;
-        outputSchema?: Record<string, unknown>;
-    }>;
-    [key: string]: unknown;
-}
-/**
- * Information about a live or declared effect
- */
-interface ToolInfo {
-    effectKey?: string;
-    /** Unique name of the effect */
-    name: string;
-    /** Description of what the effect does */
-    description?: string;
-    /** JSON Schema for effect input */
-    inputSchema?: Record<string, unknown>;
-    /** JSON Schema for effect output */
-    outputSchema?: Record<string, unknown>;
-    /** Client ID that published this effect (absent for domain-only entries) */
-    clientId?: string;
-    /** Whether the effect is ready for use (has a registered handler) */
-    ready: boolean;
-    /** Timestamp when the effect was published */
-    publishedAt?: number;
-    /** 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 effects changes
- */
-interface ToolsChangedEvent {
-    /** The current list of all available effects */
-    tools: ToolInfo[];
-    /** Names of effects that were added or updated */
-    added: string[];
-    /** 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
- */
-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 WSDisconnectInfo {
-    code?: number;
-    reason?: string;
-    wasClean?: boolean;
-    unexpected: boolean;
-    timestamp: number;
-    reconnectScheduled: boolean;
-    reconnectDelayMs?: number;
-}
-interface WSReconnectErrorInfo {
-    sessionId: string;
-    error: string;
-    timestamp: number;
-}
-interface WSClientOptions {
-    url: string;
-    sessionId: string;
-    token: string;
-    tokenProvider?: AccessTokenProvider;
-    WebSocketCtor?: any;
-    onUnexpectedClose?: (info: WSDisconnectInfo) => void;
-    onReconnectError?: (info: WSReconnectErrorInfo) => void;
-}
-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;
-}
-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
- */
-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;
-    /** Declare a build-owned effect */
-    withEffect?: ManifestEffectDeclaration;
-}
-/**
- * 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 { 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 };