@granular-software/sdk 0.4.12 → 0.4.14

package/dist/index.d.mts

@@ -86,11 +86,15 @@ interface Subject {
     updatedAt: number;
 }
 /**
- * Options for connecting to a sandbox
+ * Options for connecting to an ontology environment
  */
 interface ConnectOptions {
-    /** The sandbox name or ID to connect to */
-    sandbox: string;
+    /** The ontology name or ID to connect to */
+    ontology: string;
+    /** Named environment slot such as `dev` or `prod` */
+    environment: string;
+    /** Advanced override for the version tag/channel to follow. In the common case, omit this. */
+    tagName?: string;
     /**
      * External user identifier from your app. This is the primary input for
      * connecting to a sandbox and the only required user field in the common case.
@@ -211,11 +215,30 @@ interface AssignmentListResponse {
     items: Assignment[];
 }
 /**
- * Build policy for environments
+ * Version tracking policy for environments.
+ *
+ * Environments either follow a version tag such as `dev` or `prod`, or they
+ * pin themselves to one immutable ontology version.
  */
 interface BuildPolicy {
-    mode: 'current' | 'pinned';
+    mode: 'tag' | 'current' | 'pinned';
     buildId?: string;
+    versionId?: string;
+    tagId?: string;
+    tagName?: string;
+}
+type VersionTracking = BuildPolicy;
+interface VersionTag {
+    tagId: string;
+    sandboxId: string;
+    name: string;
+    kind: 'channel' | 'release' | 'system';
+    targetBuildId?: string | null;
+    targetVersionId?: string | null;
+    description?: string | null;
+    protected?: boolean;
+    createdAt: number;
+    updatedAt: number;
 }
 /**
  * An environment links a user (subject) to a sandbox with specific permissions
@@ -223,10 +246,18 @@ interface BuildPolicy {
 interface EnvironmentData {
     environmentId: string;
     sandboxId: string;
+    ontologyId?: string;
     buildId: string;
+    versionId: string;
     subjectId: string;
+    envName: string;
+    environment?: string;
     permissionProfileId: string;
+    tagId?: string | null;
+    tag?: VersionTag | null;
+    tracking?: BuildPolicy;
     buildPolicy: BuildPolicy;
+    updateState?: 'up_to_date' | 'update_available' | 'upgrading' | 'failed';
     createdAt: number;
     updatedAt: number;
 }
@@ -236,9 +267,19 @@ interface EnvironmentData {
 interface CreateEnvironmentData {
     /** The user/subject ID to create the environment for */
     subjectId: string;
+    /** Named environment slot such as dev or prod */
+    environment?: string;
+    /** @deprecated Use `environment` instead. */
+    envName?: string;
     /** The permission profile to apply (optional - uses assignment if not specified) */
     permissionProfileId?: string | null;
-    /** Build policy (defaults to current build) */
+    /** Follow a tag directly */
+    tagId?: string;
+    /** Follow a tag by name, typically dev or prod */
+    tagName?: string;
+    /** Pin the environment to a specific version */
+    versionId?: string;
+    /** Legacy/compat environment tracking input */
     buildPolicy?: BuildPolicy;
 }
 /**
@@ -267,25 +308,58 @@ interface ManifestListResponse {
 }
 type BuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'canceled';
 /**
- * A build represents a compiled version of a manifest
+ * An immutable ontology version derived from a specific manifest revision.
+ *
+ * The same version may have multiple build runs over time when the manifest
+ * content is unchanged but the compilation process is re-executed.
  */
 interface Build {
     buildId: string;
     sandboxId: string;
     manifestId: string;
+    manifestDigest?: string;
+    versionNumber?: number;
     status: BuildStatus;
     graphBinaryId?: string | null;
     logsUri?: string | null;
+    latestBuildRunId?: string | null;
+    buildRunId?: string;
+    createdNewVersion?: boolean;
+    environmentCount?: number;
+    laggingEnvironmentCount?: number;
+    sessionCount?: number;
     createdAt: number;
     updatedAt: number;
     isCurrent?: boolean;
 }
+type Version = Build;
 /**
- * List response for builds
+ * List response for versions
  */
 interface BuildListResponse {
     items: Build[];
 }
+interface SemanticVersionDiffEntry {
+    operationId: string;
+    kind: 'create' | 'update' | 'relationship' | 'effect' | 'unknown';
+    changeType: 'added' | 'removed' | 'changed';
+    label: string;
+    additive: boolean;
+    breaking: boolean;
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+}
+interface SemanticVersionDiff {
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        additive: number;
+        breaking: number;
+        onlyAdditiveChanges: boolean;
+    };
+    entries: SemanticVersionDiffEntry[];
+}
 /**
  * Effect handler for static/global effects: receives (input, context)
  */
@@ -304,6 +378,38 @@ interface EffectHandlerContext {
         identityId?: string;
         principalId?: string;
     };
+    behaviors?: ResolvedEffectBehaviors;
+    invocation?: EffectInvocationMetadata;
+}
+interface ResolvedEffectPostCondition {
+    condition: string;
+    description?: string;
+}
+interface ResolvedEffectDryRun {
+    enabled: boolean;
+    description?: string;
+}
+interface ResolvedEffectReverse {
+    handler?: string;
+    description?: string;
+}
+interface ResolvedEffectApprovalRequired {
+    required: boolean;
+    reason?: string;
+    mode?: string;
+}
+interface ResolvedEffectBehaviors {
+    postCondition?: ResolvedEffectPostCondition;
+    dryRun?: ResolvedEffectDryRun;
+    reverse?: ResolvedEffectReverse;
+    approvalRequired?: ResolvedEffectApprovalRequired;
+}
+type EffectInvocationMode = 'execute' | 'dryRun' | 'reverse';
+interface EffectInvocationMetadata {
+    mode?: EffectInvocationMode;
+    reverseHandler?: string;
+    sourceEffectKey?: string;
+    sourceEffectName?: string;
 }
 type ToolHandler = (input: any, context: EffectHandlerContext) => Promise<unknown>;
 /**
@@ -373,6 +479,8 @@ interface ToolSchema {
      * passed as the first argument to the handler).
      */
     static?: boolean;
+    /** Declarative runtime behaviors attached to the effect. */
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 type EffectSchema = ToolSchema;
 /**
@@ -387,6 +495,8 @@ type EffectSchema = ToolSchema;
  */
 interface ToolWithHandler extends ToolSchema {
     handler: ToolHandler | InstanceToolHandler;
+    dryRunHandler?: ToolHandler | InstanceToolHandler;
+    reverseHandler?: ToolHandler | InstanceToolHandler;
 }
 type EffectWithHandler = ToolWithHandler;
 /**
@@ -411,6 +521,7 @@ interface DomainState {
         description?: string;
         inputSchema?: Record<string, unknown>;
         outputSchema?: Record<string, unknown>;
+        metamodels?: ManifestEffectMetamodelSpec;
     }>;
     [key: string]: unknown;
 }
@@ -437,6 +548,8 @@ interface ToolInfo {
     className?: string;
     /** Whether this is a static method */
     static?: boolean;
+    /** Declarative runtime behaviors attached to the effect. */
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 interface EffectInfo extends ToolInfo {
 }
@@ -795,6 +908,65 @@ interface ManifestPropertySpec {
     type?: string;
     description?: string;
     required?: boolean;
+    note?: string | string[];
+    enum?: string[] | ManifestEnumRuleSpec;
+    filterBy?: boolean | string[] | ManifestFilterBySpec;
+    validate?: ManifestValidationRuleSpec[];
+}
+type ManifestValidationOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'true' | 'false' | 'regex' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with';
+interface ManifestEnumRuleSpec {
+    values: string[];
+    message?: string;
+}
+interface ManifestFilterBySpec {
+    operators: string[];
+    scalarType?: string;
+}
+interface ManifestValidationRuleSpec {
+    operator: ManifestValidationOperator;
+    stringValue?: string;
+    numberValue?: number;
+    booleanValue?: boolean;
+    message?: string;
+}
+interface ManifestStateMachineStateSpec {
+    name: string;
+    isFinal?: boolean;
+}
+interface ManifestStateMachineTransitionSpec {
+    name: string;
+    from: string;
+    to: string;
+}
+interface ManifestStateMachineSpec {
+    name: string;
+    entryState: string;
+    states: Array<string | ManifestStateMachineStateSpec>;
+    transitions: ManifestStateMachineTransitionSpec[];
+    finalStates?: string[];
+}
+interface ManifestPostConditionSpec {
+    condition: string;
+    description?: string;
+}
+interface ManifestDryRunSpec {
+    enabled?: boolean;
+    description?: string;
+}
+interface ManifestReverseSpec {
+    handler?: string;
+    description?: string;
+}
+interface ManifestApprovalRequiredSpec {
+    required?: boolean;
+    reason?: string;
+    mode?: string;
+}
+interface ManifestEffectMetamodelSpec {
+    postCondition?: string | ManifestPostConditionSpec;
+    dryRun?: boolean | ManifestDryRunSpec;
+    reverse?: string | ManifestReverseSpec;
+    approvalRequired?: boolean | ManifestApprovalRequiredSpec;
 }
 /**
  * Relationship definition between two classes
@@ -832,6 +1004,7 @@ interface ManifestEffectDeclaration {
     outputSchema?: ManifestEffectSchema;
     stability?: 'stable' | 'experimental' | 'deprecated';
     tags?: string[];
+    metamodels?: ManifestEffectMetamodelSpec;
 }
 /**
  * A single operation in a manifest volume
@@ -847,6 +1020,10 @@ interface ManifestOperation {
     instanceOf?: string;
     /** Define submodels/fields */
     has?: Record<string, ManifestPropertySpec>;
+    /** Advisory notes attached to the model/class itself */
+    note?: string | string[];
+    /** State machines attached to the created or targeted class */
+    stateMachines?: ManifestStateMachineSpec[];
     /** Define a relationship between two classes */
     defineRelationship?: ManifestRelationshipDef;
     /** Declare a build-owned effect */
@@ -1150,8 +1327,16 @@ declare class Environment extends Session {
     get environmentId(): string;
     /** The sandbox ID */
     get sandboxId(): string;
+    /** The ontology ID */
+    get ontologyId(): string;
     /** The subject ID */
     get subjectId(): string;
+    /** The named environment slot, such as dev or prod */
+    get envName(): string;
+    /** The named environment slot, such as dev or prod */
+    get environment(): string;
+    /** The resolved ontology version backing this environment */
+    get versionId(): string;
     /** Internal Granular user identifier for this environment */
     get granularId(): string;
     /** The permission profile ID */
@@ -1384,6 +1569,13 @@ declare class Environment extends Session {
      * Strips the alias prefix, returning the bare model path.
      */
     private _resolveAlias;
+    private _runGraphql;
+    private _applyFieldMetamodels;
+    private _applyModelMetamodels;
+    private _ensureWorkspaceToolsRoot;
+    private _storeEffectSchemas;
+    private _applyEffectMetamodels;
+    private _applyEffectDeclaration;
     /**
      * Apply a single manifest operation via GraphQL
      */
@@ -1515,7 +1707,7 @@ declare class Granular {
     recordUser(options: RecordUserOptions): Promise<User>;
     private resolveConnectUser;
     /**
-     * Connect to a sandbox and establish a real-time environment session.
+     * Connect to an ontology environment and establish a real-time session.
      *
      * Effects are registered at the sandbox level via `granular.registerEffect()`
      * or `granular.registerEffects()`. Sessions pick up live availability from
@@ -1527,7 +1719,8 @@ declare class Granular {
      * @example
      * ```typescript
      * const environment = await granular.connect({
-     *   sandbox: 'my-sandbox',
+     *   ontology: 'my-ontology',
+     *   environment: 'dev',
      *   userId: 'user_123',
      *   permissions: ['agent'],
      * });
@@ -1547,13 +1740,14 @@ declare class Granular {
      *
      * console.log(await job.result); // 'Hello!'
      * ```
-     */
+    */
     connect(options: ConnectOptions): Promise<Environment>;
     private activateEnvironment;
     private getSandboxEffectMap;
     private serializeEffect;
     private publishSandboxEffectCatalog;
     private syncSandboxEffectCatalog;
+    private recoverEffectHost;
     private startEffectHostHeartbeat;
     private stopEffectHostHeartbeat;
     private synchronizeEffectHost;
@@ -1656,4 +1850,13 @@ 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, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, 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 RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, 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 };
+type EffectRuntimeRequest = {
+    effectKey: string;
+    effectName: string;
+    input: unknown;
+    context?: EffectHandlerContext;
+};
+declare function normalizeEffectBehaviors(value?: ManifestEffectMetamodelSpec | ResolvedEffectBehaviors | null): ResolvedEffectBehaviors;
+declare function invokeRegisteredEffect(effectMap: Map<string, ToolWithHandler>, request: EffectRuntimeRequest): Promise<unknown>;
+
+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 EffectInvocationMetadata, type EffectInvocationMode, type EffectSchema, type EffectWithHandler, type EffectsChangedEvent, type EndpointMode, Environment, type EnvironmentData, type EnvironmentListResponse, type EnvironmentRecordImportSummary, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, type JobFeedbackInput, type JobFeedbackMetadata, type JobFeedbackRecord, type JobFeedbackSentiment, type JobFeedbackToolCall, type JobStatus, type JobSubmitResult, type Manifest, type ManifestApprovalRequiredSpec, type ManifestContent, type ManifestDryRunSpec, type ManifestEffectDeclaration, type ManifestEffectMetamodelSpec, type ManifestEffectSchema, type ManifestEnumRuleSpec, type ManifestFilterBySpec, type ManifestImport, type ManifestListResponse, type ManifestOperation, type ManifestPostConditionSpec, type ManifestPropertySpec, type ManifestRelationshipDef, type ManifestReverseSpec, type ManifestStateMachineSpec, type ManifestStateMachineStateSpec, type ManifestStateMachineTransitionSpec, type ManifestValidationOperator, type ManifestValidationRuleSpec, type ManifestVolume, type ModelRef, type PermissionProfile, type PermissionProfileListResponse, type PermissionRules, type Prompt, type PublishEffectsResult, type PublishToolsResult, type RPCRequest, type RPCRequestFromServer, type RPCResponse, type RecordImport, type RecordImportItem, type RecordImportItemStatus, type RecordImportStats, type RecordImportStatus, type RecordObjectOptions, type RecordObjectResult, type RecordUserOptions, type RelationshipInfo, type ResolvedEffectApprovalRequired, type ResolvedEffectBehaviors, type ResolvedEffectDryRun, type ResolvedEffectPostCondition, type ResolvedEffectReverse, type Sandbox, type SandboxListResponse, type SemanticVersionDiff, type SemanticVersionDiffEntry, 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, type Version, type VersionTag, type VersionTracking, WSClient, type WSClientOptions, type WSDisconnectInfo, type WSReconnectErrorInfo, invokeRegisteredEffect, normalizeEffectBehaviors };