@granular-software/sdk 0.4.13 → 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)
  */
@@ -1253,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 */
@@ -1625,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
@@ -1637,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'],
      * });
@@ -1657,7 +1740,7 @@ declare class Granular {
      *
      * console.log(await job.result); // 'Hello!'
      * ```
-     */
+    */
     connect(options: ConnectOptions): Promise<Environment>;
     private activateEnvironment;
     private getSandboxEffectMap;
@@ -1776,4 +1859,4 @@ type EffectRuntimeRequest = {
 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, 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, invokeRegisteredEffect, normalizeEffectBehaviors };
+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 };

package/dist/index.d.ts

@@ -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)
  */
@@ -1253,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 */
@@ -1625,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
@@ -1637,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'],
      * });
@@ -1657,7 +1740,7 @@ declare class Granular {
      *
      * console.log(await job.result); // 'Hello!'
      * ```
-     */
+    */
     connect(options: ConnectOptions): Promise<Environment>;
     private activateEnvironment;
     private getSandboxEffectMap;
@@ -1776,4 +1859,4 @@ type EffectRuntimeRequest = {
 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, 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, invokeRegisteredEffect, normalizeEffectBehaviors };
+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 };

package/dist/index.js

@@ -5613,6 +5613,19 @@ function normalizeUser(user) {
     permissions: Array.isArray(user.permissions) ? user.permissions : []
   };
 }
+function normalizeEnvironmentData(environment) {
+  const buildPolicy = environment.buildPolicy || environment.tracking || (environment.tagId ? { mode: "tag", tagId: environment.tagId } : { mode: "pinned", versionId: environment.versionId || environment.buildId });
+  const environmentName = environment.environment || environment.envName || "prod";
+  return {
+    ...environment,
+    ontologyId: environment.ontologyId || environment.sandboxId,
+    versionId: environment.versionId || environment.buildId,
+    envName: environmentName,
+    environment: environmentName,
+    buildPolicy,
+    tracking: environment.tracking || buildPolicy
+  };
+}
 var Environment = class extends Session {
   envData;
   _apiKey;
@@ -5631,10 +5644,26 @@ var Environment = class extends Session {
   get sandboxId() {
     return this.envData.sandboxId;
   }
+  /** The ontology ID */
+  get ontologyId() {
+    return this.envData.ontologyId || this.envData.sandboxId;
+  }
   /** The subject ID */
   get subjectId() {
     return this.envData.subjectId;
   }
+  /** The named environment slot, such as dev or prod */
+  get envName() {
+    return this.envData.envName;
+  }
+  /** The named environment slot, such as dev or prod */
+  get environment() {
+    return this.envData.environment || this.envData.envName;
+  }
+  /** The resolved ontology version backing this environment */
+  get versionId() {
+    return this.envData.versionId || this.envData.buildId;
+  }
   /** Internal Granular user identifier for this environment */
   get granularId() {
     return this.envData.subjectId;
@@ -6606,7 +6635,7 @@ var Granular = class {
     throw new Error("connect() requires either userId, granularId, or a user object returned by recordUser().");
   }
   /**
-   * 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
@@ -6618,7 +6647,8 @@ var Granular = class {
    * @example
    * ```typescript
    * const environment = await granular.connect({
-   *   sandbox: 'my-sandbox',
+   *   ontology: 'my-ontology',
+   *   environment: 'dev',
    *   userId: 'user_123',
    *   permissions: ['agent'],
    * });
@@ -6638,17 +6668,28 @@ var Granular = class {
    * 
    * console.log(await job.result); // 'Hello!'
    * ```
-   */
+  */
   async connect(options) {
     const clientId = options.clientId || `client_${Date.now()}`;
+    const ontology = options.ontology;
+    if (!ontology) {
+      throw new Error("connect() requires `ontology`.");
+    }
+    const environmentName = options.environment;
+    if (!environmentName) {
+      throw new Error("connect() requires `environment`.");
+    }
+    const tagName = options.tagName?.trim() || void 0;
     const user = await this.resolveConnectUser(options);
-    const sandbox = await this.findOrCreateSandbox(options.sandbox);
+    const sandbox = await this.findOrCreateSandbox(ontology);
     for (const profileName of user.permissions) {
       const profileId = await this.ensurePermissionProfile(sandbox.sandboxId, profileName);
       await this.ensureAssignment(user.granularId, sandbox.sandboxId, profileId);
     }
     const envData = await this.environments.create(sandbox.sandboxId, {
       subjectId: user.granularId,
+      environment: environmentName,
+      tagName,
       permissionProfileId: null
     });
     await this.activateEnvironment(envData.environmentId);
@@ -7083,16 +7124,22 @@ var Granular = class {
         const result = await this.request(
           `/control/sandboxes/${sandboxId}/environments`
         );
-        return result.items;
+        return result.items.map(normalizeEnvironmentData);
       },
       get: async (environmentId) => {
-        return this.request(`/control/environments/${environmentId}`);
+        return normalizeEnvironmentData(
+          await this.request(`/control/environments/${environmentId}`)
+        );
       },
       create: async (sandboxId, data) => {
-        return this.request(`/control/sandboxes/${sandboxId}/environments`, {
+        const environmentName = data.environment || data.envName;
+        return normalizeEnvironmentData(await this.request(`/control/sandboxes/${sandboxId}/environments`, {
           method: "POST",
-          body: JSON.stringify(data)
-        });
+          body: JSON.stringify({
+            ...data,
+            envName: environmentName
+          })
+        }));
       },
       delete: async (environmentId) => {
         return this.request(`/control/environments/${environmentId}`, {