@opengeni/sdk 4.0.2 → 5.0.0-canary.0

package/README.md

@@ -1,5 +1,52 @@
 # @opengeni/sdk
 
+## External-user admission (implementation branch)
+
+On a product backend, `client.asUser(externalId, { source? })` returns a separate
+client that sends the external actor assertion with the organization key. IDs
+are opaque and case-sensitive; the default source is `default`. Keep the key and
+this client server-side. Each request requires the intersection of the key's
+permissions and the user's explicit workspace membership. API-key rotation does
+not change the external identity.
+
+Use the service client—not an `asUser` client—to call
+`addExternalWorkspaceMember(workspaceId, { identity: { externalId, source? }, permissions })`
+for explicit onboarding. It requires `members:manage`, cannot grant more than
+the key permits, excludes Personal workspaces, and refuses to overwrite an
+existing membership with different permissions. Ordinary `asUser` calls never
+restore removed workspace membership or reactivate disabled identities.
+
+Service `removeWorkspaceMember` supports external members through the existing
+fenced workspace teardown. Account-wide `updateExternalIdentityMembership(
+organizationId, organizationMembershipId, { kind, expectedAuthorizationRevision,
+operationId, reason? })` requires explicit `account:admin` and supports suspend,
+reactivate, and offboard. The membership ID is returned by onboarding; its initial
+authorization revision is 1. Retain the returned revision for subsequent changes.
+Reactivation restores admission, not revoked memberships or work. Offboarding
+follows existing retention policy and cannot be reactivated through this API.
+Native-user targets and `asUser` calls are rejected by this service endpoint.
+
+An `asUser` client can discover/access its own provisioned Personal workspace
+under the key's permission ceiling. Core private session operations retain
+organization readiness/settings and explicit sharing acknowledgments; service
+clients gain no Personal-workspace fallback.
+
+Optional native-account delegation uses `beginIdentityLink`, authenticated native
+`previewIdentityLink`/`confirmIdentityLink`, and explicit server-side
+`asLinkedUser(externalId, { source?, linkId, expectedLinkRevision })`. Confirmation
+requires the actual native login plus the one-time host challenge; an organization
+key cannot confirm for the native user. `listIdentityLinks(workspaceId, cursor?)`
+returns only the effective participant's links in that organization (50 per page).
+`revokeIdentityLink` requires the observed revision. Linking never changes ordinary
+`asUser`, merges histories or transfers credentials. Link-dependent accepted work
+retains revocation checks across schedules and children. Short-lived inline MCP
+credentials remain supported, and durable renewal stays opt-in.
+
+Connect accepts an optional `installationTarget: { instanceKey, displayName,
+expectedInstanceVersion? }`. Keep the exact observed version for an existing named
+account. Setup freezes the target through callback and operation review; omitting
+it creates an independent named account instead of overwriting a default instance.
+
 Framework-agnostic TypeScript SDK for the OpenGeni public API: a typed client,
 session lifecycle, and the streaming core — SSE event streaming with automatic
 reconnect, resume-by-sequence, gap backfill, and duplicate suppression — plus
@@ -36,10 +83,10 @@ const og = new OpenGeni({
 
 const chat = await og.chat({
   tenant: "acme", // one workspace per customer, created on first use
-  user: "u_42", // opaque end-user label (required for memory: "user")
-  conversation: "c_9", // stable id, namespaced to user; the session id is derived from both
+  user: "u_42", // authenticated product user; onboard workspace membership first
+  conversation: "c_9", // stable conversation id, independent of the acting user
   agentAccess: "session", // "session" (default) | "user" | "workspace"
-  memory: "user", // "session" | "user" | "workspace" | false; default follows agentAccess
+  memory: "user", // "user" | "workspace" | false; session-only agent reach defaults to false
   create: { sandboxBackend: "none" }, // raw create-request passthrough for a pure chat
 });
 
@@ -54,7 +101,7 @@ for await (const chunk of chat.stream("and then?")) {
 // Your endpoint. `resolve` is your auth hook: identity comes from the request
 // you authenticated, never from the body. The handler reads the client's
 // conversation id itself (x-opengeni-conversation header, or the wire format's
-// own field) and scopes it to `user`; return `conversation` from resolve only
+// own field) and authorizes as `user`; return `conversation` from resolve only
 // when the host names it, which is required when there is no `user`.
 export const handler = createChatHandler(og, {
   resolve: async (request) => {
@@ -69,9 +116,11 @@ export const GET = handler; // conversation history, for restoring the chat on r
 export const POST = handler; // send a message, or answer a pending request at .../respond
 ```
 
-Conversation ids are namespaced per user: the same `conversation` for two
-`user` labels reaches two sessions, so a client cannot continue another user's
-chat by guessing its id. Without a `user`, the host must name the conversation
+Conversation IDs do not change with the acting user. Authorized collaborators
+can use the same session; private visibility prevents access by other users.
+Use `chatBySessionId` for existing and legacy user-namespaced conversations.
+User mode requires explicit workspace membership and never restores removed
+membership automatically. Without a `user`, the host must name the conversation
 from `resolve`. The Vercel and OpenAI adapters send only the latest user
 message; the earlier messages in that request are imported once, as context on
 the first message of a conversation, after which OpenGeni owns the history.
@@ -82,7 +131,7 @@ shares the customer's documents, instructions, and integrations:
 
 | Scenario                                          | `agentAccess` | `memory`      |
 | ------------------------------------------------- | ------------- | ------------- |
-| Every chat isolated (support desk)                | `"session"`   | `"session"`   |
+| Agent confined to its chat tree (support desk)    | `"session"`   | `false`       |
 | One user's chats see each other, not other users' | `"user"`      | `"user"`      |
 | Everything in the tenant shared                   | `"workspace"` | `"workspace"` |
 | Shared agent access, no memory                    | any           | `false`       |
@@ -155,7 +204,7 @@ manager. `createOrganizationApiKey(organizationId, { name, access: "read" })`
 mints a read-only master key: it inventories shared workspaces and reads their
 sessions, events, and files, but cannot create sessions, send messages, or mint
 keys, and every key reports its tier as `apiKey.access`. Either tier can call
-`listOrganizationSessions(organizationId, { limit, cursor, endUser, status })`
+`listOrganizationSessions(organizationId, { limit, cursor, scopeSubjectId, status })`
 for one page of sessions across every shared workspace (each row carries its
 `workspaceId`; private sessions and Personal workspaces never appear), or
 `iterateOrganizationSessions` to follow `nextCursor` to the end.

package/dist/artifact-client.d.ts

@@ -1,7 +1,9 @@
 import { OpenGeniDocumentAuthorityClient } from "./document-authority-client.js";
 import type { FetchResponse } from "./client.js";
+import type { SiteToolCallRequest } from "./site-tool-bridge.js";
+import type { ToolGatewayCallResponse } from "./types.js";
+import type { CreateWorkspaceArtifactRequest, PublishWorkspaceArtifactVersionRequest, WorkspaceArtifactContentResponse, WorkspaceArtifactMutationResponse } from "./workspace-artifacts.js";
 import type { CreateEditableArtifactMaterializationRequest, CreateEditableArtifactResourceRequest, EditableArtifactListResource, EditableArtifactMaterializationJobResource, EditableArtifactPinnedVersionResource, EditableArtifactResource, ImportEditableArtifactResourceRequest, ListSessionEditableArtifactResourcesOptions, PinEditableArtifactVersionRequest, ReadEditableArtifactMaterializationOptions, ReadEditableArtifactResourceOptions } from "./editable-artifact-resources.js";
-import type { CreateWorkspaceArtifactRequest, PublishWorkspaceArtifactVersionRequest, RollbackWorkspaceArtifactRequest, SetWorkspaceArtifactStatusRequest, WorkspaceArtifactContentResponse, WorkspaceArtifactDetailResponse, WorkspaceArtifactListOptions, WorkspaceArtifactListResponse, WorkspaceArtifactMutationResponse } from "./workspace-artifacts.js";
 /** Public SDK client. Optional operator and artifact operations stay out of the console core. */
 export declare class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
     createEditableArtifact(workspaceId: string, request: CreateEditableArtifactResourceRequest, options?: Readonly<{
@@ -21,11 +23,19 @@ export declare class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
     getEditableArtifactMaterialization(workspaceId: string, artifactId: string, jobId: string, options: ReadEditableArtifactMaterializationOptions): Promise<EditableArtifactMaterializationJobResource>;
     /** The caller owns the returned bounded response stream. */
     downloadEditableArtifactMaterialization(workspaceId: string, artifactId: string, jobId: string, options: ReadEditableArtifactMaterializationOptions): Promise<FetchResponse>;
-    listWorkspaceArtifacts(workspaceId: string, options?: WorkspaceArtifactListOptions): Promise<WorkspaceArtifactListResponse>;
-    getWorkspaceArtifact(workspaceId: string, artifactId: string): Promise<WorkspaceArtifactDetailResponse>;
-    getWorkspaceArtifactContent(workspaceId: string, artifactId: string, versionId?: string): Promise<WorkspaceArtifactContentResponse>;
-    createWorkspaceArtifact(workspaceId: string, request: CreateWorkspaceArtifactRequest): Promise<WorkspaceArtifactMutationResponse>;
-    publishWorkspaceArtifactVersion(workspaceId: string, artifactId: string, request: PublishWorkspaceArtifactVersionRequest): Promise<WorkspaceArtifactMutationResponse>;
-    rollbackWorkspaceArtifact(workspaceId: string, artifactId: string, request: RollbackWorkspaceArtifactRequest): Promise<WorkspaceArtifactMutationResponse>;
-    setWorkspaceArtifactStatus(workspaceId: string, artifactId: string, request: SetWorkspaceArtifactStatusRequest): Promise<WorkspaceArtifactMutationResponse>;
+    /** Exact Site-version gateway call. Keep this client on the authenticated host;
+     * the API enforces live viewer access and the version's declared tool allowlist. */
+    callWorkspaceSiteTool(workspaceId: string, request: SiteToolCallRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<ToolGatewayCallResponse>;
+    getWorkspaceArtifactContent(workspaceId: string, artifactId: string, versionOrOptions?: string | {
+        versionId?: string;
+        signal?: AbortSignal;
+    }): Promise<WorkspaceArtifactContentResponse>;
+    createWorkspaceArtifact(workspaceId: string, request: CreateWorkspaceArtifactRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceArtifactMutationResponse>;
+    publishWorkspaceArtifactVersion(workspaceId: string, artifactId: string, request: PublishWorkspaceArtifactVersionRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<WorkspaceArtifactMutationResponse>;
 }

package/dist/artifacts.js

@@ -1,10 +1,10 @@
 import {
   OpenGeniClient
-} from "./chunk-3IZMCD2K.js";
-import "./chunk-O23OOWJK.js";
-import "./chunk-2H7P45YQ.js";
+} from "./chunk-TOB3B4ZJ.js";
+import "./chunk-4YAL54F3.js";
+import "./chunk-UQGHX4DI.js";
 import "./chunk-QTBAMHEF.js";
-import "./chunk-WNEGCYCE.js";
+import "./chunk-TARU5CD2.js";
 import "./chunk-OO5LPTO7.js";
 export {
   OpenGeniClient

package/dist/browser.js

@@ -8,12 +8,12 @@ import {
 } from "./chunk-FMLDFJ2Q.js";
 import {
   OpenGeniClient
-} from "./chunk-2H7P45YQ.js";
+} from "./chunk-UQGHX4DI.js";
 import "./chunk-QTBAMHEF.js";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION
-} from "./chunk-WNEGCYCE.js";
+} from "./chunk-TARU5CD2.js";
 import {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,

package/dist/chat/ids.d.ts

@@ -2,9 +2,9 @@
  * Deterministic chat identities. A conversation id maps to exactly one
  * session id per workspace, so any process can address the same session
  * without storing a mapping, and a double-submitted create collapses through
- * the idempotency key. With an end-user label the conversation id is
- * namespaced to that user, so one user cannot address another user's
- * conversation by guessing its id.
+ * the idempotency key. The optional legacy label argument is retained only to
+ * reproduce historical addresses. New chat calls do not use it: authorization
+ * is independent of addressing, so collaborators can share a conversation.
  */
 /** The end-user label a conversation is namespaced to: the product `source` plus the opaque user id. */
 export type ChatUserLabel = {

package/dist/chat/index.js

@@ -1,9 +1,13 @@
 import {
-  OpenGeniClient,
+  OpenGeniEmbeddingClient
+} from "../chunk-J5USCWPE.js";
+import "../chunk-TOB3B4ZJ.js";
+import "../chunk-4YAL54F3.js";
+import {
   parseSseStream
-} from "../chunk-2H7P45YQ.js";
+} from "../chunk-UQGHX4DI.js";
 import "../chunk-QTBAMHEF.js";
-import "../chunk-WNEGCYCE.js";
+import "../chunk-TARU5CD2.js";
 import {
   OpenGeniApiError
 } from "../chunk-OO5LPTO7.js";
@@ -303,7 +307,7 @@ var OpenGeni = class {
   constructor(options) {
     if (!options.apiKey) throw new TypeError("OpenGeni requires an apiKey.");
     if (!options.organizationId) throw new TypeError("OpenGeni requires an organizationId.");
-    this.client = new OpenGeniClient({
+    this.client = new OpenGeniEmbeddingClient({
       baseUrl: options.baseUrl ?? DEFAULT_OPENGENI_BASE_URL,
       apiKey: options.apiKey,
       ...options.fetch ? { fetch: options.fetch } : {}
@@ -335,35 +339,29 @@ var OpenGeni = class {
   }
   /**
    * Address one conversation; the session is created lazily on the first send.
-   * With a `user`, the conversation id is namespaced to that user (a different
-   * user with the same conversation id reaches a different session).
+   * Identity selects authority, not the conversation address. Workspace
+   * membership must be provisioned by the host's explicit onboarding flow.
+   * Legacy user-namespaced conversations remain accessible by their session ID.
    */
   async chat(options) {
     if (!options.conversation) throw new TypeError("chat() requires a conversation id.");
     const agentAccess = options.agentAccess ?? "session";
-    const memoryScope = options.memory === false ? "off" : options.memory === void 0 ? agentAccess : options.memory;
+    const memoryScope = options.memory === false ? "off" : options.memory === void 0 ? agentAccess === "session" ? "off" : agentAccess : options.memory;
     if (memoryScope === "user" && !options.user) {
       throw new OpenGeniChatError(
         "memory_scope_requires_user",
-        'memory: "user" requires a user label so memories can be scoped to that end user.'
+        'memory: "user" requires an authenticated product user.'
       );
     }
-    const endUser = options.user ? { source: this.source, id: options.user } : void 0;
+    const client = options.user ? this.client.asUser(options.user, { source: this.source }) : this.client;
     const workspaceId = await this.workspaceId(options);
-    const sessionId = await chatSessionId(workspaceId, options.conversation, endUser);
-    const session = await this.findSession(workspaceId, sessionId);
-    if (session && endUser && !sameEndUser(session.endUser ?? null, endUser)) {
-      throw new OpenGeniChatError(
-        "conversation_not_authorized",
-        "This conversation belongs to a different user."
-      );
-    }
+    const sessionId = options.sessionId ?? await chatSessionId(workspaceId, options.conversation);
+    const session = await this.findSession(client, workspaceId, sessionId);
     const buildCreate = (text, importedHistory) => {
       const context = options.create?.modelContext === void 0 && importedHistory ? formatImportedHistory(importedHistory) : void 0;
       return {
         agentAccess,
         memoryScope,
-        ...endUser ? { endUser } : {},
         ...options.model !== void 0 ? { model: options.model } : {},
         ...options.instructions !== void 0 ? { instructions: options.instructions } : {},
         ...options.skills !== void 0 ? { skills: options.skills } : {},
@@ -375,7 +373,7 @@ var OpenGeni = class {
         idempotencyKey: chatIdempotencyKey(sessionId)
       };
     };
-    return new Chat(this, {
+    return new Chat(client, {
       workspaceId,
       sessionId,
       conversation: options.conversation,
@@ -384,22 +382,14 @@ var OpenGeni = class {
     });
   }
   /**
-   * Address an existing session by id (for example decoded from a response id).
-   * `user` is the end user the caller authenticated: the session must carry
-   * exactly that end-user label (`{ source, id }`) or the call throws
-   * `conversation_not_authorized`. Pass `null` only from trusted server code
-   * that vouches for the session itself; a session reached with `null` is not
-   * checked against any user.
+   * Address an existing session with native API authorization. The same shared
+   * session can be opened by different authorized users. Pass null only for an
+   * explicitly service-owned operation; the API still enforces service access.
    */
   async chatBySessionId(target) {
-    const session = await this.client.getSession(target.workspaceId, target.sessionId);
-    if (target.user !== null && !sameEndUser(session.endUser ?? null, { source: this.source, id: target.user })) {
-      throw new OpenGeniChatError(
-        "conversation_not_authorized",
-        "This conversation belongs to a different user."
-      );
-    }
-    return new Chat(this, {
+    const client = target.user !== null ? this.client.asUser(target.user, { source: this.source }) : this.client;
+    const session = await client.getSession(target.workspaceId, target.sessionId);
+    return new Chat(client, {
       workspaceId: target.workspaceId,
       sessionId: target.sessionId,
       conversation: null,
@@ -407,9 +397,9 @@ var OpenGeni = class {
       buildCreate: null
     });
   }
-  async findSession(workspaceId, sessionId) {
+  async findSession(client, workspaceId, sessionId) {
     try {
-      return await this.client.getSession(workspaceId, sessionId);
+      return await client.getSession(workspaceId, sessionId);
     } catch (error) {
       if (error instanceof OpenGeniApiError && error.status === 404) return null;
       throw error;
@@ -417,20 +407,20 @@ var OpenGeni = class {
   }
   async listSessions(options) {
     const workspaceId = await this.workspaceId(options);
-    return await this.client.requestJson(
+    const client = options.user ? this.client.asUser(options.user, { source: this.source }) : this.client;
+    return await client.requestJson(
       "GET",
       `/v1/workspaces/${workspaceId}/sessions`,
       void 0,
       {
-        ...options.limit !== void 0 ? { limit: String(options.limit) } : {},
-        ...options.user ? { endUserSource: this.source, endUserId: options.user } : {}
+        ...options.limit !== void 0 ? { limit: String(options.limit) } : {}
       }
     );
   }
 };
 var Chat = class {
-  constructor(og, init) {
-    this.og = og;
+  constructor(client, init) {
+    this.client = client;
     this.workspaceId = init.workspaceId;
     this.sessionId = init.sessionId;
     this.conversation = init.conversation;
@@ -482,7 +472,7 @@ var Chat = class {
     let lastAssistantTurn = null;
     let after = 0;
     while (true) {
-      const result = await this.og.client.listEventPage(this.workspaceId, this.sessionId, {
+      const result = await this.client.listEventPage(this.workspaceId, this.sessionId, {
         after,
         includeTypes: [
           "user.message",
@@ -537,7 +527,7 @@ var Chat = class {
       if (!this.buildCreate) {
         throw new OpenGeniChatError("session_missing", "This session no longer exists.");
       }
-      const created = await this.og.client.createSession(
+      const created = await this.client.createSession(
         this.workspaceId,
         this.buildCreate(text, importedHistory)
       );
@@ -546,31 +536,31 @@ var Chat = class {
         return { after: 0, turnId: created.initialTurnId };
       }
     }
-    const event = await this.og.client.sendMessage(this.workspaceId, this.sessionId, text);
+    const event = await this.client.sendMessage(this.workspaceId, this.sessionId, text);
     return submittedFrom(event);
   }
   async submitSteer(text, importedHistory) {
     if (!this.session) return await this.submit(text, importedHistory);
-    const result = await this.og.client.steerMessage(this.workspaceId, this.sessionId, text);
+    const result = await this.client.steerMessage(this.workspaceId, this.sessionId, text);
     return { after: result.accepted.sequence, turnId: result.turn.id ?? null };
   }
   async submitResponse(input) {
     let event;
     if ("decision" in input) {
-      event = await this.og.client.sendApprovalDecision(this.workspaceId, this.sessionId, {
+      event = await this.client.sendApprovalDecision(this.workspaceId, this.sessionId, {
         approvalId: input.requestId,
         decision: input.decision,
         ...input.message !== void 0 ? { message: input.message } : {}
       });
     } else if ("answers" in input) {
-      event = await this.og.client.submitHumanInputResponse(
+      event = await this.client.submitHumanInputResponse(
         this.workspaceId,
         this.sessionId,
         input.requestId,
         { outcome: "answered", answers: input.answers }
       );
     } else {
-      event = await this.og.client.submitHumanInputResponse(
+      event = await this.client.submitHumanInputResponse(
         this.workspaceId,
         this.sessionId,
         input.requestId,
@@ -587,7 +577,7 @@ var Chat = class {
     else signal?.addEventListener("abort", onAbort, { once: true });
     const fold = new ChatTurnFold(this.workspaceId, this.sessionId, submitted.turnId);
     try {
-      for await (const event of this.og.client.streamEvents(this.workspaceId, this.sessionId, {
+      for await (const event of this.client.streamEvents(this.workspaceId, this.sessionId, {
         after: submitted.after,
         signal: upstream.signal
       })) {
@@ -659,9 +649,6 @@ function abortError() {
   error.name = "AbortError";
   return error;
 }
-function sameEndUser(left, right) {
-  return left !== null && left.source === right.source && left.id === right.id;
-}
 
 // src/chat/http.ts
 var CHAT_CONVERSATION_HEADER = "x-opengeni-conversation";