@opengeni/sdk 1.0.1 → 2.3.0-canary.0

package/README.md

@@ -37,6 +37,110 @@ for await (const event of client.streamEvents(workspaceId, session.id)) {
 }
 ```
 
+## Session visibility and forks
+
+For organizations with session-tenancy activation, a canonical managed-cookie
+owner can change a fully quiescent session between private and workspace
+visibility or create an independent same-workspace private or workspace-visible fork. API keys and
+delegated/service bearers are intentionally not authority for these methods.
+The browser client below intentionally omits `apiKey`; its same-origin request
+carries the authenticated managed-session cookie.
+
+```ts
+const browserClient = new OpenGeniClient({ baseUrl: window.location.origin });
+const current = await browserClient.getSession(workspaceId, sessionId);
+if (!current.tenancy) throw new Error("Session tenancy is not activated");
+
+await browserClient.updateSessionVisibility(workspaceId, sessionId, {
+  visibility: "private",
+  expectedAuthorityEpoch: current.tenancy.authorityEpoch,
+  idempotencyKey: crypto.randomUUID(),
+});
+
+const fork = await browserClient.forkSession(workspaceId, sessionId, {
+  idempotencyKey: crypto.randomUUID(),
+  visibility: "workspace",
+  // Required when private conversation content is copied into workspace scope.
+  workspaceSharedAcknowledged: current.tenancy.visibility === "private",
+});
+```
+
+Retain each idempotency key until the request has a known outcome. If a
+transport failure reports `outcomeUnknown`, retry the same operation with the
+same key. An authority-epoch conflict requires a fresh `getSession` and a new
+user decision. A quiescence conflict identifies the stable blocker after live
+turns, goals, realtime, schedules, workspace writers, retained processes, and
+sandbox access have been settled. Forks copy exact same-workspace durable
+conversation content but no live turn, goal, credential, Connection/delegation,
+personal grant, Variable Set, Rig, MCP server configuration, process, sandbox
+identity, pin, or workflow. Destination visibility and acknowledgement are
+idempotency-bound.
+
+## Personal-resource grants
+
+The same canonical managed-cookie owner can manage explicit personal-resource
+delegations after organization activation. Pages are bounded to one exact kind;
+the server derives the only valid action and returns the full credential-free
+delegation to attach through the resource's ordinary session API.
+
+```ts
+const page = await browserClient.listUserResourceAuthorities(workspaceId, {
+  resourceKind: "connection",
+  limit: 50,
+});
+const authority = page.authorities[0];
+if (!authority) throw new Error("No personal Connection is available");
+
+const issued = await browserClient.issueUserResourceGrant(workspaceId, authority.authorityId, {
+  scope: "user",
+  resourceKind: "connection",
+  mode: "session",
+  context: "workspace_shared",
+  sessionId,
+  expectedAuthorityEpoch: current.tenancy.authorityEpoch,
+  workspaceSharedAcknowledged: true,
+});
+
+await browserClient.revokeUserResourceGrant(workspaceId, issued.grant.grantId);
+```
+
+The SDK deliberately exposes only exact-session and standing (`always`) grant
+management. It does not expose standalone `once`, custom expiry, scheduled or
+cross-workspace authority, or an atomic create-session-and-attach workflow.
+Revocation prevents future reads but cannot retract output already shared.
+
+## Scheduled connection authority
+
+Agent schedules may carry explicit personal Connection authority. The public
+request contains only the credential-free server, Connection, and common-user
+grant tuple returned by the authority-selection API; the SDK never receives or
+stores provider credentials:
+
+```ts
+const task = await client.createScheduledTask(workspaceId, {
+  name: "Daily triage",
+  schedule: { type: "calendar", hour: 8, minute: 0, timeZone: "Europe/Oslo" },
+  runMode: "reusable_session",
+  agentConfig: { prompt: "Triage the new support issues" },
+  connectionAuthorities: [selection],
+});
+```
+
+PATCH semantics are deliberate: omit `connectionAuthorities` to preserve the
+exact prior immutable selection, pass `[]` to clear it, or pass a non-empty
+array to replace and revalidate it. Execution-changing edits that preserve
+personal authority must be made by the same causal human; use an explicit fresh
+selection when authority should move. `once` grants are consumed by the durable
+scheduled occurrence, not by an activity attempt, so retries reuse the same run
+receipt. `listScheduledTaskRuns` exposes terminal occurrence state while private
+Connection ids, subjects, and authority snapshots stay server-side.
+
+Deleting a task is externally idempotent and immediately removes it from live
+lists and quota, but the server retains a tombstone plus run/session/turn audit
+evidence until workspace/account retention cleanup. A stable `triggerId` is
+still required when a caller wants manual-trigger retries to coalesce; ordinary
+scheduled fires derive their producer identity from the Temporal fire workflow.
+
 ## Realtime browser controller (`@opengeni/sdk/realtime`)
 
 The public realtime subpath owns the provider-neutral browser controller and
@@ -447,6 +551,17 @@ it is not public web search.
 const goal = await client.getGoal(workspaceId, sessionId); // counters: autoContinuations, noProgressStreak
 await client.pauseGoal(workspaceId, sessionId, { rationale: "manual review" });
 await client.resumeGoal(workspaceId, sessionId); // resets counters, re-arms continuations
+
+const revisions = await client.listGoalRevisions(workspaceId, sessionId); // legacy raw array
+const page = await client.listGoalRevisionPage(workspaceId, sessionId, { limit: 25 });
+await client.rejectGoalRevision(workspaceId, sessionId, proposalId, {
+  expectedObjectiveRevision: goal.objectiveRevision,
+  rationale: "Keep the existing objective",
+});
+await client.rollbackGoalRevision(workspaceId, sessionId, appliedRevisionId, {
+  expectedObjectiveRevision: goal.objectiveRevision,
+  rationale: "Restore the last known-good objective",
+});
 ```
 
 ## Files
@@ -530,7 +645,7 @@ Every public endpoint group has typed methods:
 | Sessions + events | `createSession`, `listSessions`, `listSessionPage`, `listAgentTopology`, `getSession`, `getSessionLineage`, `updateSession`, `listEvents`, `sendEvent`, `sendMessage`, `steerMessage`, `pauseSession`, `resumeSession`, `cancelSession`, `sendApprovalDecision`, `streamEvents`, `openEventStream` |
 | Machines (bring-your-own-compute) | `listMachines`, `machineMetricsSeries`, `swapActiveSandbox`, `mintEnrollToken`, `lookupDeviceEnrollment`, `approveDeviceEnrollment`, `denyDeviceEnrollment` |
 | Turn queue | `getQueue`, `moveQueueItem`, `editQueueItem`, `steerQueueItem`, `deleteQueueItem` |
-| Goal | `getGoal`, `updateGoal`, `pauseGoal`, `resumeGoal` |
+| Goal | `getGoal`, `updateGoal`, `pauseGoal`, `resumeGoal`, `listGoalRevisions`, `listGoalRevisionPage`, `applyGoalRevision`, `rejectGoalRevision`, `rollbackGoalRevision` |
 | Scheduled tasks | `createScheduledTask`, `listScheduledTasks`, `getScheduledTask`, `updateScheduledTask`, `pauseScheduledTask`, `resumeScheduledTask`, `triggerScheduledTask`, `deleteScheduledTask`, `listScheduledTaskRuns` |
 | Variable sets | `listVariableSets`, `createVariableSet`, `getVariableSet`, `updateVariableSet`, `deleteVariableSet`, `setVariableSetVariable`, `deleteVariableSetVariable`; generic reads are metadata-only, while dedicated permissioned exact-value reads are part of the held client train |
 | Files | `uploadFile`, `beginFileUpload`, `completeFileUpload`, `getFile`, `createFileDownloadUrl` |
@@ -542,7 +657,7 @@ Every public endpoint group has typed methods:
 | Remote Skills | `previewSkillImport`, `installSkill`, `previewSkillUninstall`, `uninstallSkill` |
 | GitHub | `getGitHubApp`, `githubConnectUrl`, `listGitHubRepositories`, `syncGitHubRepositories`, `createGitHubAppManifest` |
 | API keys | `listApiKeys`, `createApiKey`, `deleteApiKey` |
-| Billing | `getBilling`, `getBillingUsage`, `getBillingEntitlements`, `createBillingCheckout` |
+| Billing | `getBilling`, `getBillingUsage`, `getBillingEntitlements`, `createBillingCheckout`, `createBillingPortalSession` |
 
 `listIntegrationDefinitions` returns safe Integration Definition metadata without any
 deployment OAuth client credentials. API Integrations are multi-instance:

package/dist/artifacts.js

@@ -1,10 +1,10 @@
 import {
   OpenGeniClient
-} from "./chunk-TYZ4JL4J.js";
-import "./chunk-YGH5P47G.js";
-import "./chunk-4DV37UUA.js";
-import "./chunk-GU6JF75T.js";
-import "./chunk-ST5DDKJP.js";
+} from "./chunk-AGUKZAXR.js";
+import "./chunk-6IPZY27S.js";
+import "./chunk-TW5MNHUX.js";
+import "./chunk-GW3EJ2GP.js";
+import "./chunk-C4DJPZRU.js";
 export {
   OpenGeniClient
 };

package/dist/automations-client.d.ts

@@ -0,0 +1,17 @@
+import type { AutomationRun, AutomationSource, AutomationTrigger, AutomationWebhookResult, CreateAutomationSourceRequest, CreateAutomationTriggerRequest, TriggerAutomationManuallyRequest, UpdateAutomationSourceRequest, UpdateAutomationTriggerRequest } from "@opengeni/contracts";
+import type { OpenGeniClient as OpenGeniCoreClient } from "./client.js";
+export type OpenGeniAutomationsTransport = Pick<OpenGeniCoreClient, "requestJson">;
+export declare class OpenGeniAutomationsClient {
+    private readonly client;
+    constructor(client: OpenGeniAutomationsTransport);
+    listSources(workspaceId: string): Promise<AutomationSource[]>;
+    createSource(workspaceId: string, request: CreateAutomationSourceRequest): Promise<AutomationSource>;
+    updateSource(workspaceId: string, sourceId: string, request: UpdateAutomationSourceRequest): Promise<AutomationSource>;
+    disableSource(workspaceId: string, sourceId: string): Promise<void>;
+    listTriggers(workspaceId: string): Promise<AutomationTrigger[]>;
+    createTrigger(workspaceId: string, request: CreateAutomationTriggerRequest): Promise<AutomationTrigger>;
+    updateTrigger(workspaceId: string, triggerId: string, request: UpdateAutomationTriggerRequest): Promise<AutomationTrigger>;
+    disableTrigger(workspaceId: string, triggerId: string, expectedRevision: number): Promise<void>;
+    listRuns(workspaceId: string): Promise<AutomationRun[]>;
+    triggerManually(workspaceId: string, sourceId: string, request: TriggerAutomationManuallyRequest): Promise<AutomationWebhookResult>;
+}

package/dist/automations.d.ts

@@ -0,0 +1,3 @@
+export { OpenGeniAutomationsClient } from "./automations-client.js";
+export type { OpenGeniAutomationsTransport } from "./automations-client.js";
+export type { AutomationAcceptedExecution, AutomationNormalizedEvent, AutomationRun, AutomationSource, AutomationTrigger, AutomationWebhookResult, CreateAutomationSourceRequest, CreateAutomationTriggerRequest, TriggerAutomationManuallyRequest, UpdateAutomationSourceRequest, UpdateAutomationTriggerRequest, } from "@opengeni/contracts";

package/dist/automations.js

@@ -0,0 +1,78 @@
+// src/automations-client.ts
+var OpenGeniAutomationsClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async listSources(workspaceId) {
+    const result = await this.client.requestJson(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources`
+    );
+    return result.sources;
+  }
+  async createSource(workspaceId, request) {
+    return await this.client.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources`,
+      request
+    );
+  }
+  async updateSource(workspaceId, sourceId, request) {
+    return await this.client.requestJson(
+      "PATCH",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`,
+      request
+    );
+  }
+  async disableSource(workspaceId, sourceId) {
+    await this.client.requestJson(
+      "DELETE",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`
+    );
+  }
+  async listTriggers(workspaceId) {
+    const result = await this.client.requestJson(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers`
+    );
+    return result.triggers;
+  }
+  async createTrigger(workspaceId, request) {
+    return await this.client.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers`,
+      request
+    );
+  }
+  async updateTrigger(workspaceId, triggerId, request) {
+    return await this.client.requestJson(
+      "PATCH",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}`,
+      request
+    );
+  }
+  async disableTrigger(workspaceId, triggerId, expectedRevision) {
+    await this.client.requestJson(
+      "DELETE",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}?expectedRevision=${expectedRevision}`
+    );
+  }
+  async listRuns(workspaceId) {
+    const result = await this.client.requestJson(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/runs`
+    );
+    return result.runs;
+  }
+  async triggerManually(workspaceId, sourceId, request) {
+    return await this.client.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}/events`,
+      request
+    );
+  }
+};
+export {
+  OpenGeniAutomationsClient
+};
+//# sourceMappingURL=automations.js.map

package/dist/automations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/automations-client.ts"],"sourcesContent":["import type {\n  AutomationRun,\n  AutomationSource,\n  AutomationTrigger,\n  AutomationWebhookResult,\n  CreateAutomationSourceRequest,\n  CreateAutomationTriggerRequest,\n  TriggerAutomationManuallyRequest,\n  UpdateAutomationSourceRequest,\n  UpdateAutomationTriggerRequest,\n} from \"@opengeni/contracts\";\nimport type { OpenGeniClient as OpenGeniCoreClient } from \"./client\";\n\nexport type OpenGeniAutomationsTransport = Pick<OpenGeniCoreClient, \"requestJson\">;\n\nexport class OpenGeniAutomationsClient {\n  constructor(private readonly client: OpenGeniAutomationsTransport) {}\n\n  async listSources(workspaceId: string): Promise<AutomationSource[]> {\n    const result = await this.client.requestJson<{ sources: AutomationSource[] }>(\n      \"GET\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources`,\n    );\n    return result.sources;\n  }\n\n  async createSource(\n    workspaceId: string,\n    request: CreateAutomationSourceRequest,\n  ): Promise<AutomationSource> {\n    return await this.client.requestJson(\n      \"POST\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources`,\n      request,\n    );\n  }\n\n  async updateSource(\n    workspaceId: string,\n    sourceId: string,\n    request: UpdateAutomationSourceRequest,\n  ): Promise<AutomationSource> {\n    return await this.client.requestJson(\n      \"PATCH\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`,\n      request,\n    );\n  }\n\n  async disableSource(workspaceId: string, sourceId: string): Promise<void> {\n    await this.client.requestJson(\n      \"DELETE\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`,\n    );\n  }\n\n  async listTriggers(workspaceId: string): Promise<AutomationTrigger[]> {\n    const result = await this.client.requestJson<{ triggers: AutomationTrigger[] }>(\n      \"GET\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers`,\n    );\n    return result.triggers;\n  }\n\n  async createTrigger(\n    workspaceId: string,\n    request: CreateAutomationTriggerRequest,\n  ): Promise<AutomationTrigger> {\n    return await this.client.requestJson(\n      \"POST\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers`,\n      request,\n    );\n  }\n\n  async updateTrigger(\n    workspaceId: string,\n    triggerId: string,\n    request: UpdateAutomationTriggerRequest,\n  ): Promise<AutomationTrigger> {\n    return await this.client.requestJson(\n      \"PATCH\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}`,\n      request,\n    );\n  }\n\n  async disableTrigger(\n    workspaceId: string,\n    triggerId: string,\n    expectedRevision: number,\n  ): Promise<void> {\n    await this.client.requestJson(\n      \"DELETE\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}?expectedRevision=${expectedRevision}`,\n    );\n  }\n\n  async listRuns(workspaceId: string): Promise<AutomationRun[]> {\n    const result = await this.client.requestJson<{ runs: AutomationRun[] }>(\n      \"GET\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/runs`,\n    );\n    return result.runs;\n  }\n\n  async triggerManually(\n    workspaceId: string,\n    sourceId: string,\n    request: TriggerAutomationManuallyRequest,\n  ): Promise<AutomationWebhookResult> {\n    return await this.client.requestJson(\n      \"POST\",\n      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}/events`,\n      request,\n    );\n  }\n}\n"],"mappings":";AAeO,IAAM,4BAAN,MAAgC;AAAA,EACrC,YAA6B,QAAsC;AAAtC;AAAA,EAAuC;AAAA,EAEpE,MAAM,YAAY,aAAkD;AAClE,UAAM,SAAS,MAAM,KAAK,OAAO;AAAA,MAC/B;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,IACnD;AACA,WAAO,OAAO;AAAA,EAChB;AAAA,EAEA,MAAM,aACJ,aACA,SAC2B;AAC3B,WAAO,MAAM,KAAK,OAAO;AAAA,MACvB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,MACjD;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,aACJ,aACA,UACA,SAC2B;AAC3B,WAAO,MAAM,KAAK,OAAO;AAAA,MACvB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC,wBAAwB,mBAAmB,QAAQ,CAAC;AAAA,MACrG;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,cAAc,aAAqB,UAAiC;AACxE,UAAM,KAAK,OAAO;AAAA,MAChB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC,wBAAwB,mBAAmB,QAAQ,CAAC;AAAA,IACvG;AAAA,EACF;AAAA,EAEA,MAAM,aAAa,aAAmD;AACpE,UAAM,SAAS,MAAM,KAAK,OAAO;AAAA,MAC/B;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,IACnD;AACA,WAAO,OAAO;AAAA,EAChB;AAAA,EAEA,MAAM,cACJ,aACA,SAC4B;AAC5B,WAAO,MAAM,KAAK,OAAO;AAAA,MACvB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,MACjD;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,cACJ,aACA,WACA,SAC4B;AAC5B,WAAO,MAAM,KAAK,OAAO;AAAA,MACvB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC,yBAAyB,mBAAmB,SAAS,CAAC;AAAA,MACvG;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,eACJ,aACA,WACA,kBACe;AACf,UAAM,KAAK,OAAO;AAAA,MAChB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC,yBAAyB,mBAAmB,SAAS,CAAC,qBAAqB,gBAAgB;AAAA,IAC9I;AAAA,EACF;AAAA,EAEA,MAAM,SAAS,aAA+C;AAC5D,UAAM,SAAS,MAAM,KAAK,OAAO;AAAA,MAC/B;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC;AAAA,IACnD;AACA,WAAO,OAAO;AAAA,EAChB;AAAA,EAEA,MAAM,gBACJ,aACA,UACA,SACkC;AAClC,WAAO,MAAM,KAAK,OAAO;AAAA,MACvB;AAAA,MACA,kBAAkB,mBAAmB,WAAW,CAAC,wBAAwB,mBAAmB,QAAQ,CAAC;AAAA,MACrG;AAAA,IACF;AAAA,EACF;AACF;","names":[]}