@granular-software/sdk 0.4.7 → 0.4.9

package/dist/index.d.mts

@@ -458,6 +458,51 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
 type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobFeedbackSentiment = 'good' | 'bad';
+interface JobFeedbackToolCall {
+    callId?: string;
+    toolName?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number | null;
+}
+interface JobFeedbackMetadata {
+    source: 'sdk';
+    status: JobStatus;
+    code: string;
+    domainRevision?: string;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number | null;
+    result?: unknown;
+    error?: string;
+    stdout: string[];
+    stderr: string[];
+    toolCalls: JobFeedbackToolCall[];
+}
+interface JobFeedbackInput {
+    sentiment: JobFeedbackSentiment;
+    comment?: string | null;
+}
+interface JobFeedbackRecord {
+    feedbackId: string;
+    tenantId?: string;
+    sessionId: string;
+    environmentId: string;
+    sandboxId?: string;
+    buildId?: string;
+    subjectId?: string;
+    jobId: string;
+    sentiment: JobFeedbackSentiment;
+    comment?: string | null;
+    metadata: JobFeedbackMetadata & Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
 /**
  * Result from submitting a job
  */
@@ -474,6 +519,8 @@ interface Job {
     status: JobStatus;
     /** Promise that resolves with the job result */
     result: Promise<unknown>;
+    /** Attach user feedback to this job and persist it with job/session metadata */
+    leaveFeedback(input: JobFeedbackInput): Promise<JobFeedbackRecord>;
     /** Subscribe to job events */
     on(event: string, handler: (data: unknown) => void): void;
 }
@@ -677,6 +724,58 @@ interface RecordObjectResult {
     /** Whether the instance was newly created (false = updated) */
     created: boolean;
 }
+type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+interface RecordImportStats {
+    totalRecords: number;
+    queuedRecords: number;
+    processingRecords: number;
+    completedRecords: number;
+    failedRecords: number;
+    canceledRecords: number;
+    awaitingRecords: number;
+}
+interface RecordImportItem {
+    itemId: string;
+    importId: string;
+    tenantId: string;
+    environmentId: string;
+    className: string;
+    id: string;
+    label: string | null;
+    fields: Record<string, string | number | boolean | null> | null;
+    relationships: Record<string, string | string[]> | null;
+    status: RecordImportItemStatus;
+    attempts: number;
+    errorMessage: string | null;
+    resultPath: string | null;
+    resultCreated: boolean | null;
+    createdAt: number;
+    updatedAt: number;
+    processedAt: number | null;
+}
+interface RecordImport {
+    importId: string;
+    tenantId: string;
+    environmentId: string;
+    sandboxId: string;
+    subjectId: string;
+    status: RecordImportStatus;
+    batchSize: number;
+    errorMessage: string | null;
+    createdAt: number;
+    updatedAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+    canceledAt: number | null;
+    stats: RecordImportStats;
+}
+interface EnvironmentRecordImportSummary extends RecordImportStats {
+    environmentId: string;
+    totalImports: number;
+    activeImports: number;
+    updatedAt: number;
+}
 /**
  * Property specification in a manifest operation
  */
@@ -815,6 +914,7 @@ declare class WSClient {
     private isExplicitlyDisconnected;
     private options;
     constructor(options: WSClientOptions);
+    get currentSessionId(): string;
     private clearTokenRefreshTimer;
     private decodeBase64Url;
     private getTokenExpiryMs;
@@ -884,8 +984,10 @@ declare class Session {
     /** Last known tools for diffing */
     private lastKnownTools;
     constructor(client: WSClient, clientId?: string);
+    private extractDomainRevisionFromDoc;
     private buildLegacyEffectContext;
     get document(): Doc<Record<string, unknown>>;
+    get sessionId(): string;
     get domainRevision(): string | null;
     /**
      * Make a raw RPC call to the session's Durable Object.
@@ -1057,6 +1159,7 @@ declare class Environment extends Session {
      */
     getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
+    private controlPlaneRequest;
     /**
      * Close the session and disconnect from the sandbox.
      *
@@ -1314,6 +1417,39 @@ declare class Environment extends Session {
      * ```
      */
     recordObject(options: RecordObjectOptions): Promise<RecordObjectResult>;
+    /**
+     * Batch version of `recordObject()`.
+     *
+     * Sends several upserts through the control-plane batch endpoint so the
+     * server can collapse the graph mutations into far fewer round trips.
+     */
+    recordObjects(records: RecordObjectOptions[]): Promise<RecordObjectResult[]>;
+    /**
+     * Queue a background record import for this environment.
+     */
+    enqueueRecordImport(records: RecordObjectOptions[], options?: {
+        batchSize?: number;
+    }): Promise<RecordImport>;
+    /**
+     * List queued or completed record imports for this environment.
+     */
+    listRecordImports(status?: RecordImportStatus): Promise<RecordImport[]>;
+    /**
+     * Fetch the latest aggregate import counters for this environment.
+     */
+    getRecordImportSummary(): Promise<EnvironmentRecordImportSummary>;
+    /**
+     * Convenience helper returning queued + processing records for this environment.
+     */
+    getAwaitingRecordCount(): Promise<number>;
+    /**
+     * Fetch a single record import by id.
+     */
+    getRecordImport(importId: string): Promise<RecordImport>;
+    /**
+     * Cancel a queued/background record import.
+     */
+    cancelRecordImport(importId: string): Promise<RecordImport>;
     /**
      * Removed: environment-scoped effect publication is no longer supported.
      */
@@ -1513,4 +1649,4 @@ 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, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, 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 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 };
+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 };

package/dist/index.d.ts

@@ -458,6 +458,51 @@ interface EffectsChangedEvent extends ToolsChangedEvent {
 type EffectHandler = ToolHandler;
 type InstanceEffectHandler = InstanceToolHandler;
 type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timeout' | 'canceled';
+type JobFeedbackSentiment = 'good' | 'bad';
+interface JobFeedbackToolCall {
+    callId?: string;
+    toolName?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number | null;
+}
+interface JobFeedbackMetadata {
+    source: 'sdk';
+    status: JobStatus;
+    code: string;
+    domainRevision?: string;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    durationMs?: number | null;
+    result?: unknown;
+    error?: string;
+    stdout: string[];
+    stderr: string[];
+    toolCalls: JobFeedbackToolCall[];
+}
+interface JobFeedbackInput {
+    sentiment: JobFeedbackSentiment;
+    comment?: string | null;
+}
+interface JobFeedbackRecord {
+    feedbackId: string;
+    tenantId?: string;
+    sessionId: string;
+    environmentId: string;
+    sandboxId?: string;
+    buildId?: string;
+    subjectId?: string;
+    jobId: string;
+    sentiment: JobFeedbackSentiment;
+    comment?: string | null;
+    metadata: JobFeedbackMetadata & Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
 /**
  * Result from submitting a job
  */
@@ -474,6 +519,8 @@ interface Job {
     status: JobStatus;
     /** Promise that resolves with the job result */
     result: Promise<unknown>;
+    /** Attach user feedback to this job and persist it with job/session metadata */
+    leaveFeedback(input: JobFeedbackInput): Promise<JobFeedbackRecord>;
     /** Subscribe to job events */
     on(event: string, handler: (data: unknown) => void): void;
 }
@@ -677,6 +724,58 @@ interface RecordObjectResult {
     /** Whether the instance was newly created (false = updated) */
     created: boolean;
 }
+type RecordImportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+type RecordImportItemStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
+interface RecordImportStats {
+    totalRecords: number;
+    queuedRecords: number;
+    processingRecords: number;
+    completedRecords: number;
+    failedRecords: number;
+    canceledRecords: number;
+    awaitingRecords: number;
+}
+interface RecordImportItem {
+    itemId: string;
+    importId: string;
+    tenantId: string;
+    environmentId: string;
+    className: string;
+    id: string;
+    label: string | null;
+    fields: Record<string, string | number | boolean | null> | null;
+    relationships: Record<string, string | string[]> | null;
+    status: RecordImportItemStatus;
+    attempts: number;
+    errorMessage: string | null;
+    resultPath: string | null;
+    resultCreated: boolean | null;
+    createdAt: number;
+    updatedAt: number;
+    processedAt: number | null;
+}
+interface RecordImport {
+    importId: string;
+    tenantId: string;
+    environmentId: string;
+    sandboxId: string;
+    subjectId: string;
+    status: RecordImportStatus;
+    batchSize: number;
+    errorMessage: string | null;
+    createdAt: number;
+    updatedAt: number;
+    startedAt: number | null;
+    finishedAt: number | null;
+    canceledAt: number | null;
+    stats: RecordImportStats;
+}
+interface EnvironmentRecordImportSummary extends RecordImportStats {
+    environmentId: string;
+    totalImports: number;
+    activeImports: number;
+    updatedAt: number;
+}
 /**
  * Property specification in a manifest operation
  */
@@ -815,6 +914,7 @@ declare class WSClient {
     private isExplicitlyDisconnected;
     private options;
     constructor(options: WSClientOptions);
+    get currentSessionId(): string;
     private clearTokenRefreshTimer;
     private decodeBase64Url;
     private getTokenExpiryMs;
@@ -884,8 +984,10 @@ declare class Session {
     /** Last known tools for diffing */
     private lastKnownTools;
     constructor(client: WSClient, clientId?: string);
+    private extractDomainRevisionFromDoc;
     private buildLegacyEffectContext;
     get document(): Doc<Record<string, unknown>>;
+    get sessionId(): string;
     get domainRevision(): string | null;
     /**
      * Make a raw RPC call to the session's Durable Object.
@@ -1057,6 +1159,7 @@ declare class Environment extends Session {
      */
     getHeap(): SessionHeapSnapshot;
     private getRuntimeBaseUrl;
+    private controlPlaneRequest;
     /**
      * Close the session and disconnect from the sandbox.
      *
@@ -1314,6 +1417,39 @@ declare class Environment extends Session {
      * ```
      */
     recordObject(options: RecordObjectOptions): Promise<RecordObjectResult>;
+    /**
+     * Batch version of `recordObject()`.
+     *
+     * Sends several upserts through the control-plane batch endpoint so the
+     * server can collapse the graph mutations into far fewer round trips.
+     */
+    recordObjects(records: RecordObjectOptions[]): Promise<RecordObjectResult[]>;
+    /**
+     * Queue a background record import for this environment.
+     */
+    enqueueRecordImport(records: RecordObjectOptions[], options?: {
+        batchSize?: number;
+    }): Promise<RecordImport>;
+    /**
+     * List queued or completed record imports for this environment.
+     */
+    listRecordImports(status?: RecordImportStatus): Promise<RecordImport[]>;
+    /**
+     * Fetch the latest aggregate import counters for this environment.
+     */
+    getRecordImportSummary(): Promise<EnvironmentRecordImportSummary>;
+    /**
+     * Convenience helper returning queued + processing records for this environment.
+     */
+    getAwaitingRecordCount(): Promise<number>;
+    /**
+     * Fetch a single record import by id.
+     */
+    getRecordImport(importId: string): Promise<RecordImport>;
+    /**
+     * Cancel a queued/background record import.
+     */
+    cancelRecordImport(importId: string): Promise<RecordImport>;
     /**
      * Removed: environment-scoped effect publication is no longer supported.
      */
@@ -1513,4 +1649,4 @@ 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, Granular, type GranularAuth, type GranularOptions, type GraphQLResult, type InstanceEffectHandler, type InstanceToolHandler, type Job, 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 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 };
+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 };