diff --git a/.claude/skills/openbot-copy/SKILL.md b/.claude/skills/openbot-copy/SKILL.md index c3a0abee95..231b0263f2 100644 --- a/.claude/skills/openbot-copy/SKILL.md +++ b/.claude/skills/openbot-copy/SKILL.md @@ -28,6 +28,9 @@ One word for one thing, everywhere a person can see it. | **connect / disconnect / reconnect** | What a person does to their own account. | link (except GitHub and Slack identity, where "link" is the vendor's own word) | | **skill** | A named instruction invoked with `/`. | command, prompt | | **admin** | The person who runs OpenBot for everybody. | administrator, owner, operator | +| **organization**, **everyone in the organization** | Everybody who uses OpenBot together, and what is theirs as a whole: "everyone in the organization", "organization rules", "your organization's shared account". | team, the whole team, teammates, organisation | +| **team**, **Teams** | A named group of people inside one organization, made in Admin under Teams or kept in step with the company's directory. Whatever can be given to everyone can be given to a team. | group (for a team), and never the whole organization | +| **shared account** | An app account the organization connects once, which Bots act as. | team account | | **OpenBot** | The product the person is using, and their account with it: "Sign in to OpenBot", "your OpenBot account". | this deployment, the server, the instance, CopilotKit | | **OpenBot by CopilotKit** | The company, only where it has to be named: the license agreement's name, a legal or privacy line, the one place setup says who makes OpenBot. | CopilotKit alone | | **turn on / turn off** | An admin switching an app or a feature. | enable / disable (in sentences; a switch may still read "Enabled") | @@ -101,7 +104,11 @@ because the admin is the one who sets them. A page anybody can open may not. 8. **Buttons are verbs**: Connect, Request access, Create, Save. A button never says "Click here" or "OK" when it does something specific. 9. **Errors**: what failed, in the person's terms, and one next step. "Couldn't load your - connections. Reload the page." No stack of reasons, no blame. + connections. Try again in a moment." No stack of reasons, no blame. Never "Reload the page": the + same screens show in the OpenBot Desktop window, which has no reload button. While OpenBot + Desktop can't reach the OpenBot it is connected to, one line says so and the screens wait + (`lib/desktop/connection-lost.ts`), so a section's error is never the place to name that cause. + `tests/no-reload-the-page-in-user-copy.test.ts` reads every shown string. 10. **Empty states** say what will appear and how: "No skills yet. Write one with New skill." ## Before And After @@ -109,7 +116,7 @@ because the admin is the one who sets them. A page anybody can open may not. | Before | After | |---|---| | The apps and accounts your Bots use as you. Open one to connect it or change it. | Connect your accounts so Bots can use apps on your behalf. | -| Your connected accounts could not be loaded, so nothing is listed here rather than a list that may be wrong. Reload the page, and tell an administrator if it persists. | Couldn't load your connections. Reload the page, or ask an admin if it keeps happening. | +| Your connected accounts could not be loaded, so nothing is listed here rather than a list that may be wrong. Reload the page, and tell an administrator if it persists. | Couldn't load your connections. Try again in a moment, or ask an admin if it keeps happening. | | Sent to the coworker it is for. Type @ to choose one yourself. | OpenBot picks the right Bot. Type @ to choose one. | | Gmail is a Composio app, and this deployment has no Composio key. (to a non-admin) | Gmail isn't set up yet. An admin has to turn it on. | | The agent is still working on another request. Please wait or stop that task first. | This Bot is still working on something. Wait for it, or stop it first. | @@ -120,6 +127,7 @@ because the admin is the one who sets them. A page anybody can open may not. |---|---| | "agent" or "coworker" for a Bot | Bot | | "administrator" | admin | +| "team", "the whole team" or "teammates" for everybody | "everyone in the organization", or "organization"; a team is one named group inside it | | "this deployment" on a page anybody can open | OpenBot, or say what is missing | | "CopilotKit" alone: "Sign in to CopilotKit", "your CopilotKit account" | OpenBot, or "OpenBot by CopilotKit" where the company must be named | | A sentence over ~25 words | Split it, or cut the clause that justifies the screen | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9b72b7ab19..d36f230750 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -190,9 +190,13 @@ jobs: # holding still as an update gets ready, Home's message box holding still while the # microphone's notice shows, a reply staying where it was written once its turn is over, # every skin's top-left corner clear of the Mac window's buttons, OpenDots' Bots badge on its - # icon's corner inside the rail, the version in the account row read whole, a Bot's orb - # one color in the sidebar, on its page and at the top of its conversation, and Record on - # screen with a Bot's page in a window of any width, which only a browser's layout, cascade + # icon's corner inside the rail, the version in the account row read whole, an organization's + # name in the account menu read whole or in a tooltip, a Bot's orb + # one color in the sidebar, on its page and at the top of its conversation, Record on + # screen with a Bot's page in a window of any width, the team screens and a Bot's + # Publish dialog holding their layout wide, narrow and on a phone, and the Admin screens + # where a rule or a grant names a team holding theirs wide and on a phone, which only a + # browser's layout, cascade # and paint resolve, and the app following the system's light or dark, which only a # browser's `prefers-color-scheme` reports, with what OpenBot Desktop's window is told of # it. The @@ -200,7 +204,7 @@ jobs: # test script's pretest does). - run: | bun run generate:app-config - bun test app/tests/tool-line-reduced-motion.test.tsx app/tests/onboarding-window-buttons.test.tsx app/tests/onboarding-orb-room.test.tsx app/tests/transcript-rail-clearance.test.tsx app/tests/a2ui-frame.test.tsx app/tests/update-banner-layout.test.tsx app/tests/composer-dictation-notice-layout.test.tsx app/tests/conversation-intro-halo.test.tsx app/tests/transcript-room.test.tsx app/tests/skins-window-buttons.test.tsx app/tests/opendots-rail-badge.test.tsx app/tests/account-version-layout.test.tsx app/tests/bot-orb-one-color.test.tsx app/tests/theme-follows-system.test.tsx app/tests/desktop-window-theme.test.tsx app/tests/bot-screen-record-layout.test.tsx + bun test app/tests/tool-line-reduced-motion.test.tsx app/tests/onboarding-window-buttons.test.tsx app/tests/onboarding-orb-room.test.tsx app/tests/transcript-rail-clearance.test.tsx app/tests/a2ui-frame.test.tsx app/tests/update-banner-layout.test.tsx app/tests/composer-dictation-notice-layout.test.tsx app/tests/conversation-intro-halo.test.tsx app/tests/transcript-room.test.tsx app/tests/skins-window-buttons.test.tsx app/tests/opendots-rail-badge.test.tsx app/tests/account-version-layout.test.tsx app/tests/organization-menu-names.test.tsx app/tests/bot-orb-one-color.test.tsx app/tests/theme-follows-system.test.tsx app/tests/desktop-window-theme.test.tsx app/tests/bot-screen-record-layout.test.tsx app/tests/teams-screens-layout.test.tsx app/tests/team-grants-screens-layout.test.tsx env: OPENBOT_APP_BROWSER: '1' # The desktop setup window's, for the same reason: the AI step's form holding still while the diff --git a/.github/workflows/desktop-build.yml b/.github/workflows/desktop-build.yml index 7de63f4918..a29f8ac9a8 100644 --- a/.github/workflows/desktop-build.yml +++ b/.github/workflows/desktop-build.yml @@ -85,7 +85,7 @@ jobs: with: bun-version: 1.4.3 no-cache: ${{ inputs.channel == 'release' || runner.os == 'Windows' }} - - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1 with: toolchain: stable - if: inputs.channel != 'release' diff --git a/.github/workflows/desktop-macos-signing.yml b/.github/workflows/desktop-macos-signing.yml index b4d1c5a7fb..a867058cfe 100644 --- a/.github/workflows/desktop-macos-signing.yml +++ b/.github/workflows/desktop-macos-signing.yml @@ -301,7 +301,7 @@ jobs: # must come from the tree and the lockfiles, not from anything an earlier run left behind. # The standard library for the architecture this job builds, which on the Apple silicon # runner is a second target for the Intel build. - - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1 with: toolchain: stable targets: ${{ matrix.platform.rust-target }} diff --git a/.github/workflows/desktop-shell-updates.yml b/.github/workflows/desktop-shell-updates.yml index 39087a9594..121a15ff1d 100644 --- a/.github/workflows/desktop-shell-updates.yml +++ b/.github/workflows/desktop-shell-updates.yml @@ -69,7 +69,7 @@ jobs: - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: 1.4.3 - - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1 with: toolchain: stable - name: Linux packaging dependencies diff --git a/.github/workflows/desktop-signing.yml b/.github/workflows/desktop-signing.yml index d47e0d4962..eed32a6195 100644 --- a/.github/workflows/desktop-signing.yml +++ b/.github/workflows/desktop-signing.yml @@ -134,7 +134,7 @@ jobs: with: bun-version: 1.4.3 no-cache: true - - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1 with: toolchain: stable - name: Install pinned AzureSignTool diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml index 9eb018f3f9..b492ff884b 100644 --- a/.github/workflows/desktop.yml +++ b/.github/workflows/desktop.yml @@ -41,7 +41,7 @@ jobs: with: ref: ${{ github.event.pull_request.head.sha || github.sha }} persist-credentials: false - - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml index 99b02c8145..7870df3c61 100644 --- a/.github/workflows/publish-release.yml +++ b/.github/workflows/publish-release.yml @@ -610,7 +610,7 @@ jobs: with: bun-version: 1.4.3 no-cache: true - - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # v1 with: toolchain: stable - run: | diff --git a/CHANGELOG.md b/CHANGELOG.md index 56df252441..4257402222 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,16 @@ every deployment: ### OpenBot Desktop +- **OpenBot Desktop can connect to an OpenBot that runs somewhere else.** At set-up, and later in + Settings, Computer, choose between OpenBot on this computer, as before, and an OpenBot at an + address you type, such as your company's. Connected, nothing is installed or started on this + computer and no CopilotKit account is asked for: you sign in to that OpenBot in your browser, and + the app keeps the sign-in in Keychain or Windows Credential Manager, never in a file. Settings + shows where the app is connected, with Sign out and a way back to OpenBot on this computer, + which loses nothing. Starting, stopping and updating OpenBot's services, model keys and local + folders for Bots belong to OpenBot on this computer and are not shown while connected. It needs + an OpenBot whose server honours an app's sign-in for its screens; an earlier one is refused with + a sentence saying so. - **OpenBot Desktop is one address.** With CopilotKit Intelligence on the same machine, the app used to open a second connection, straight to Intelligence's gateway on a port of its own. It now opens everything on OpenBot's own address: the server carries that socket @@ -350,6 +360,11 @@ earlier release's is one top-level line in it, `x-openbot-scheduled-work: server person, is sent as `Authorization: Bearer` or `x-api-key`, and works on `/api/v2` only. The server also issues access tokens through OAuth 2.1 with PKCE, which work on `/api/v2` only too. Both end when the person is removed. +- **Settings has an API keys page.** Under You, a signed-in person lists their keys, creates one + by name and revokes one. A new key is shown once, with Copy. OpenBot on one computer for one + person has no sign-in and says it has no keys, and OpenBot Desktop connected to an OpenBot + elsewhere opens the page in your browser. The spec now lists what an app needs for OAuth: the + client ids, redirect addresses, endpoints and how long tokens last. - **The web app calls the new addresses**, through a client generated from the spec, for Bots, the audit trail, accounts, admin settings, model connections, notifications, routines, conversations and approvals, and opens its sockets there. Apps, connections, a Bot's grants, diff --git a/api/accepted-breaking-changes.md b/api/accepted-breaking-changes.md index 2b2f036998..e03406dba2 100644 --- a/api/accepted-breaking-changes.md +++ b/api/accepted-breaking-changes.md @@ -34,3 +34,14 @@ Once the change is on the base branch, oasdiff no longer reports it and its line - 2026-11-14 POST /api/v2/organizations/{organizationId}/people/{personId}/revoke-access added the new `member` enum value to the `person/role` response property for the response status `200`. Renamed before any release to the organisation-member roles: owner, admin and member, where a person was admin or user. - 2026-11-14 POST /api/v2/organizations/{organizationId}/people/{personId}/revoke-access added the new `owner` enum value to the `person/role` response property for the response status `200`. Renamed before any release to the organisation-member roles: owner, admin and member, where a person was admin or user. - 2026-11-14 PATCH /api/v2/organizations/{organizationId}/capabilities/{capabilityId} removed the request property `roles/user`. Renamed before any release to the organisation-member roles: owner, admin and member, where a person was admin or user. +- 2026-11-15 POST /api/v2/organizations/{organizationId}/members api removed without deprecation. Adding somebody who already had an account, by email, was described before any release and no release serves it. People join an organization by invitation: POST /api/v2/organizations/{organizationId}/invitations, which the person accepts. +- 2026-11-15 PUT /api/v2/organizations/{organizationId}/apps/{appId}/account-mode added the new `team` enum value to the `bots/items/approval/members/items/kind` response property for the response status `200`. A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team. +- 2026-11-15 GET /api/v2/organizations/{organizationId}/bots/{botId}/shared-use added the new `team` enum value to the `apps/items/approval/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `apps/items/needed/members/items/kind`, `pending/items/current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` and 1 more). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team. +- 2026-11-15 POST /api/v2/organizations/{organizationId}/capabilities/batch-update added the new `team` enum value to the `saved/items/scopeKind` response property for the response status `200`. A permission switch can now be set for a team by id, beside the organization, a role and a directory group; a client that never set one never reads one. +- 2026-11-15 POST /api/v2/organizations/{organizationId}/capabilities/preview added the new `team` enum value to the `people/items/capabilities/items/after/decidedBy` response property for the response status `200` (shared schema: `CapabilityAnswer`, also at `people/items/capabilities/items/before/decidedBy`). A team's switch can now be the one that decides a person's permission, as a directory group's can. +- 2026-11-15 POST /api/v2/organizations/{organizationId}/capabilities/translate added the new `team` enum value to the `changes/items/scopeKind` response property for the response status `200`. A permission switch can now be set for a team by id, beside the organization, a role and a directory group; a client that never set one never reads one. +- 2026-11-15 GET /api/v2/organizations/{organizationId}/network-policies added the new `team` enum value to the `networkPolicies/items/scopeKind` response property for the response status `200`. A network policy can now be set for a team by id, beside the organization and a directory group; a client that never set one never reads one. +- 2026-11-15 PUT /api/v2/organizations/{organizationId}/network-policies/{networkPolicyId} added the new `team` enum value to the `scopeKind` response property for the response status `200`. A network policy can now be set for a team by id, beside the organization and a directory group; a client that never set one never reads one. +- 2026-11-15 GET /api/v2/organizations/{organizationId}/shared-use-requests added the new `team` enum value to the `sharedUseRequests/items/current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `sharedUseRequests/items/proposed/members/items/kind`). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team. +- 2026-11-15 POST /api/v2/organizations/{organizationId}/shared-use-requests/{sharedUseRequestId}/approve added the new `team` enum value to the `current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `proposed/members/items/kind`). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team. +- 2026-11-15 POST /api/v2/organizations/{organizationId}/shared-use-requests/{sharedUseRequestId}/decline added the new `team` enum value to the `current/oneOf[#/components/schemas/SharedUseApproval]/members/items/kind` response property for the response status `200` (shared schema: `SharedUseApproval`, also at `proposed/members/items/kind`). A shared account's audience can now name a team by id beside a person and a directory group; nothing is taken from a client, and one written before teams never sent or approved a team. \ No newline at end of file diff --git a/api/asyncapi.yaml b/api/asyncapi.yaml index e4461570dc..d3b64aff46 100644 --- a/api/asyncapi.yaml +++ b/api/asyncapi.yaml @@ -61,8 +61,18 @@ servers: join token carries the address to dial with it (realtime.clientUrl). Where Intelligence runs beside an OpenBot, that address is OpenBot's own, so a client dials one host: either /api/intelligence/client, which - OpenBot relays and which also asks for the person's session, or - /client, which the deployment's edge sends straight to the gateway. + OpenBot relays, or /client, which the deployment's edge sends straight + to the gateway. The relayed address also asks who is connecting, with + the same credential that made the join token: the web app's session, an + app's access token (conversations:read) or an API key, the last two as + Authorization: Bearer on the request that opens the socket, or a key in + an x-api-key header. So a script that holds only an API key mints a + join token with it and opens the socket with it. A credential that is + not valid is answered 401 before the socket opens. A join token the + gateway refuses, because it was used already or has expired, closes the + relayed socket with code 1008 and the reason "This join token has been + used or has expired. Ask for a new one."; 1011 means the gateway could + not be reached at all. security: - $ref: "#/components/securitySchemes/joinToken" voiceService: @@ -187,8 +197,11 @@ channels: A Bot's runs in one conversation thread, as AG-UI events, on the gateway's socket for clients. The socket speaks the Phoenix Channels protocol, version 2: every frame is a JSON array of five items, [join - reference, reference, topic, event, payload]. The topic is - thread:{threadId}, and a join token opens exactly one thread. + reference, reference, topic, event, payload]. The topic is the one the + REST answer gave as realtime.topic, and a join token opens exactly one + thread. The topic names the thread as the gateway knows it, which in an + organization other than default is not the threadId a client has, so a + client uses the topic as given and never makes one from threadId. A client joins the topic, and the gateway answers with connected, then @@ -540,7 +553,8 @@ components: organizationId: description: >- The organization, by its id or its slug, which the caller must be a - member of. Every install has one addressed as default. + member of. One the caller is not in answers as one that does not + exist, default included. botId: description: The Bot whose computer it is. messages: @@ -1142,7 +1156,9 @@ components: ThreadTopic: type: string pattern: ^thread:.+$ - description: The thread, as thread:{threadId}. + description: >- + The thread, as thread: and the gateway's name for it: the topic the + REST answer gave (realtime.topic), used as given. ThreadJoinFrame: type: array description: "[join reference, reference, topic, \"phx_join\", payload]" diff --git a/api/client-boundary.allow.ts b/api/client-boundary.allow.ts index 1418acd262..8caca0162f 100644 --- a/api/client-boundary.allow.ts +++ b/api/client-boundary.allow.ts @@ -304,6 +304,31 @@ export const ALLOWED: Allowed[] = [ rule: "hand-built-v2", why: "the Recorder host's handoff, from Rust, which has no generated client", }, + // Desktop connecting to an OpenBot that runs somewhere else. + { + file: "desktop/src-tauri/src/connected/address.rs", + what: "/api/v2/organizations/default/deployment", + rule: "hand-built-v2", + why: "whether the address a person typed is an OpenBot, asked from Rust before anybody signs in", + }, + { + file: "desktop/src-tauri/src/connected/address.rs", + what: "/.well-known/oauth-authorization-server/api/auth", + rule: "before-sign-in", + why: "OAuth's discovery document, which names the sign-in's addresses", + }, + { + file: "desktop/src-tauri/src/connected/sign_in.rs", + what: "/api/copilotkit/info", + rule: "runtime", + why: "whether the OpenBot serves its runtime to an app's sign-in, asked once after signing in", + }, + { + file: "desktop/src-tauri/src/connected/relay.rs", + what: /^\/(api\/?|\.well-known\/)$/, + rule: "transport", + why: "the relay that carries the window's requests to the OpenBot it is connected to: the starts of the paths it signs in, naming no address of its own", + }, // Path tables the server registers today's routes from. ...["shared/bot-browser.ts", "shared/openbot-browser.ts"].map( (file): Allowed => ({ diff --git a/api/openapi-bot-grants.test.ts b/api/openapi-bot-grants.test.ts index b08ef1db4f..cb4f92aa50 100644 --- a/api/openapi-bot-grants.test.ts +++ b/api/openapi-bot-grants.test.ts @@ -82,12 +82,14 @@ test("each operation asks for its area's permission, read to look and write to c "deleteAppAccessRequest", "deleteBotGrant", "dismissAppAccessRequest", + "getAppTeamGrants", "getBotApp", "giveBotApp", "listAppAccessRequests", "listBotApps", "listBotGrants", "listGiveableApps", + "replaceAppTeamGrants", "replaceBotGrant", "replayBotGrants", "takeBackBotApp", diff --git a/api/openapi-components.test.ts b/api/openapi-components.test.ts index 5c0b446f9c..472054758c 100644 --- a/api/openapi-components.test.ts +++ b/api/openapi-components.test.ts @@ -86,7 +86,7 @@ test("a skill's slug is the one the skill form lets a person type", () => { test("each operation asks for its own area's scope: reading to read, writing to change", () => { const found = operations(); - expect(found).toHaveLength(19); + expect(found).toHaveLength(21); for (const { path, method, tag, scopes } of found) { const area = tag === "Skills" ? "skills" : "components"; // Checking whether a Bot may draw a component, and reading its data, change nothing a person set. diff --git a/api/openapi-organizations.test.ts b/api/openapi-organizations.test.ts new file mode 100644 index 0000000000..05da36cd6a --- /dev/null +++ b/api/openapi-organizations.test.ts @@ -0,0 +1,52 @@ +import { expect, test } from "bun:test"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { parse } from "yaml"; + +/** + * The list of a person's own organizations, as an app's token reads it. A token carries no session, + * so the OpenBot-Organization header says which organization it works in, and the list marks that + * one active. The header is checked against the person's membership as on every address that names + * no organization, so one they are not in answers not found. The spec declares both, so a client + * generated from it knows the header and the answer. + */ + +type Parameter = { + name?: string; + in?: string; + required?: boolean; + $ref?: string; +}; +type Operation = { + parameters?: Parameter[]; + responses?: Record; +}; + +const spec = parse( + readFileSync(join(import.meta.dir, "openapi.yaml"), "utf8"), +) as { + paths: Record>; + components: { parameters: Record }; +}; + +const listOrganizations = spec.paths["/api/v2/people/me/organizations"]?.get; + +const parameters = (listOrganizations?.parameters ?? []).map((parameter) => + parameter.$ref + ? spec.components.parameters[ + parameter.$ref.replace("#/components/parameters/", "") + ] + : parameter, +); + +test("listOrganizations declares the header an app's token names its organization with", () => { + expect( + parameters.find((parameter) => parameter?.name === "OpenBot-Organization"), + ).toMatchObject({ in: "header", required: false }); +}); + +test("listOrganizations declares the not found a header naming an organization the caller isn't in answers", () => { + expect(listOrganizations?.responses?.["404"]?.$ref).toBe( + "#/components/responses/OrganizationNotFound", + ); +}); diff --git a/api/openapi.yaml b/api/openapi.yaml index 4c4461c240..e7279feb85 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -8,7 +8,11 @@ info: description: |- The one API every OpenBot client uses: the web app, Desktop, mobile and the Recorder. It follows the conventions of CopilotKit Intelligence's v2 API so both read as one API, and OpenBot's resources sit beside Intelligence's under the same organization address (/api/v2/organizations/{organizationId}/...). Errors are RFC 9457 problem details (application/problem+json), lists page with an opaque cursor and a limit, and every write takes an Idempotency-Key. - An OpenBot install holds one or more organizations, and a person may be a member of several. Every install has the organization `default`, which is where everybody starts. organizationId is an organization's id or its slug, and the caller must be a member of it: an organization the caller is not in answers exactly as one that does not exist. + An OpenBot install holds one or more organizations, and a person may be a member of several. Where an install allows more than one, everybody has an organization of their own, made for them when they first sign in, and joins others by invitation. Otherwise, and on an install for one person with no sign-in, everybody works in the organization `default`. organizationId is an organization's id or its slug, and the caller must be a member of it: an organization the caller is not in answers exactly as one that does not exist, `default` included. + + A program of your own signs its requests in one of two ways. An API key acts as the person who made it, in every organization they are a member of, like a personal access token: the address names the organization each request is for. Keys start `obk_` and are sent as `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2 and on the socket a join token is spent on (createConversationJoinToken). To get a first key, sign in to OpenBot's web app, open Settings, then API keys, and create one. The key is shown once. Only a person signed in to the web app can make or delete keys: a key or an app's sign-in cannot. An app that signs people in uses OAuth 2.1 instead, described under the appOAuth security scheme: its client ids, redirect addresses, endpoints, how long tokens last and the four addresses outside /api/v2 a token also works at. + + An install for one person on one computer has no sign-in. It signs nobody in, so it has neither OAuth nor API keys, and the operations that manage keys and sessions answer 503 with the code SIGN_IN_UNAVAILABLE. This file is the single source of truth: the clients, the server's types, the docs and the contract tests are all generated from it or checked against it. A change that breaks an existing client fails the pull request. servers: @@ -30,7 +34,7 @@ tags: - name: Identity providers description: The companies' own identity providers registered for single sign-on, by email domain. Only an administrator manages them. - name: API keys - description: The keys a person makes for automation. A key acts as them, inside the organization, on the API only, and only a person signed in to OpenBot can make or manage one. + description: The keys a person makes for automation. A key acts as them, in every organization they are a member of, on the API, and only a person signed in to OpenBot can make or manage one. - name: Sessions description: Where a person is signed in to OpenBot, so they can see each browser and device and sign one out. - name: Organization settings @@ -46,11 +50,11 @@ tags: - name: Voice description: 'Voice calls with a conversation''s Bot: how a call connects, and the calls a person saved in a conversation with their transcripts.' - name: Credentials - description: 'The vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them.' + description: 'The organization''s vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them.' - name: Models description: The models Bots can run on, and the one a person chose for each of their conversations. - name: Apps - description: The apps this OpenBot has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here. + description: The apps the organization has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here. - name: Connections description: 'A person''s connections to apps: the accounts they signed in with so their Bots can act there for them, and an app''s one shared account when an administrator connects it for everybody.' - name: Bot grants @@ -79,6 +83,8 @@ tags: description: Work a Bot scheduled for itself to come back to later in a conversation. - name: Organizations description: The organizations the caller is a member of, and each one's members. An organization keeps its own Bots and conversations, apart from every other's. + - name: Teams + description: 'An organization''s teams: named groups of its members, and each team''s people. What is granted to a team is its people''s to use, and nobody else''s in the organization. A team is made here or kept in step with a group of the company''s directory.' - name: Approvals description: 'What a person''s Bots are waiting on them for: the actions that ask before they run, the questions a Bot asked, and what the person set for themselves about asking (their preferences, their own rules, and what they allowed for one conversation). Each person''s are theirs alone.' - name: Approval rules @@ -168,7 +174,7 @@ paths: - Bots operationId: listBots summary: List Bots - description: 'Return one page of the Bots the caller can see: theirs, the ones shared with them, the ones assigned to them and the ones that come with OpenBot, oldest first, and by id among Bots made at the same moment. hidden=true lists only the Bots the caller hid from their own list instead. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the Bots the caller can see: theirs, the ones shared with them, the ones assigned to them and the ones that come with OpenBot, oldest first, and by id among Bots made at the same moment. Somebody else''s private Bot is never among them, an admin''s list included. hidden=true lists only the Bots the caller hid from their own list instead. scope=organization lists every Bot in the organization, people''s private Bots included, for an admin''s screens that decide what Bots may hold; it is refused to anybody who is not an admin of the organization. Somebody else''s private Bot comes withheld there: its name and avatar, and nothing from inside it (see the Bot''s withheld). A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -181,6 +187,15 @@ paths: schema: type: boolean default: false + - name: scope + in: query + description: 'Whose Bots: caller, the Bots the caller can see; organization, every Bot in the organization, for an admin of it only.' + schema: + type: string + enum: + - caller + - organization + default: caller - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' responses: @@ -412,7 +427,7 @@ paths: - Audit events operationId: listAuditEvents summary: List audit events - description: Return one page of the audit trail, newest first, narrowed by the filters given. Each filter narrows the events, and a filter that takes several values separated by commas matches any of them. A value that names nothing in the trail matches no event rather than being refused. A missing cursor starts at the newest event and nextCursor null ends the list. A cursor belongs to the filters that made it, so changing a filter starts again without one; limit may change from page to page. Only an administrator may read the trail. + description: 'Return one page of the organization''s audit trail, newest first, narrowed by the filters given. Each organization has its own trail, and an event is on the trail of the organization it happened in. What happens to the organization itself is on its trail too: organization.created, organization.renamed, organization.member_invited, organization.invitation_canceled, organization.member_joined, organization.member_removed and organization.member_role_changed. Each filter narrows the events, and a filter that takes several values separated by commas matches any of them. A value that names nothing in the trail matches no event rather than being refused. A missing cursor starts at the newest event and nextCursor null ends the list. A cursor belongs to the filters that made it, so changing a filter starts again without one; limit may change from page to page. Only an administrator of the organization may read its trail.' security: - webSession: [] - appOAuth: @@ -469,7 +484,7 @@ paths: - Audit events operationId: exportAuditEvents summary: Export audit events as CSV - description: 'Return every event the filters match, newest first, as one CSV file (RFC 4180): the same filters as listing audit events, without its paging, so the file and the list agree. The file holds at most 5,000 events; when more match, OpenBot-Export-Truncated says how many it holds, and narrowing the dates exports the rest. A cell a spreadsheet would run as a formula starts with an apostrophe. Each export is recorded on the trail. Only an administrator may export the trail.' + description: 'Return every event the filters match, newest first, as one CSV file (RFC 4180): the same filters as listing audit events, without its paging, so the file and the list agree. The file holds at most 5,000 events; when more match, OpenBot-Export-Truncated says how many it holds, and narrowing the dates exports the rest. A cell a spreadsheet would run as a formula starts with an apostrophe. Each export is recorded on the trail. Only an administrator of the organization may export its trail.' x-openbot-singleton: true security: - webSession: [] @@ -777,7 +792,7 @@ paths: - People operationId: revokePersonAccess summary: Remove a person's access - description: 'Stop a person from using OpenBot: their address can''t sign in again, and the sessions, API keys and app sign-ins they hold end at once. They keep their record and their history, and restoring their access lets them sign in again. Their connected credentials are retired too. Only an administrator may do this, never to themselves, and never to somebody the deployment''s configuration names as an administrator. Removing somebody already removed retires anything left and records nothing new.' + description: 'Remove a person from the organization. Where everybody has an organization of their own (an OpenBot whose list of organizations answers canCreate true), this ends their membership of this organization alone: they lose its Bots and conversations from their next request, and their account, sessions, API keys, their own organization and any other they belong to are unchanged. Restoring them puts the membership back with its role and teams. Where OpenBot keeps one organization, it stops the person using OpenBot: their address can''t sign in again, and the sessions, API keys and app sign-ins they hold end at once; restoring their access lets them sign in again. Either way they keep their record and their history, and the credentials they connected here are retired. Only an administrator may do this, never to themselves, never to somebody the deployment''s configuration names as an administrator, and never to the organization''s owner. Removing somebody already removed retires anything left and records nothing new.' security: - webSession: [] - appOAuth: @@ -821,7 +836,7 @@ paths: - People operationId: restorePersonAccess summary: Give a person their access back - description: 'Let a removed person sign in again. What ended when they were removed stays ended: they sign in afresh and make new API keys. Only an administrator may do this. Restoring somebody who was never removed changes nothing and records nothing.' + description: 'Give a removed person their access back. Where everybody has an organization of their own, this puts back their membership of this organization with the role and teams it had; their sessions and API keys, which were never ended, work here again from their next request. Where OpenBot keeps one organization, it lets them sign in again, and what ended when they were removed stays ended: they sign in afresh and make new API keys. Only an administrator may do this. Restoring somebody who was never removed changes nothing and records nothing.' security: - webSession: [] - appOAuth: @@ -1188,7 +1203,7 @@ paths: - API keys operationId: createApiKey summary: Make an API key - description: 'Make an API key that acts as the person, inside this organization, on the API only. The key itself is in this answer and never again: OpenBot keeps only a hash of it. Only the person themselves may make one, signed in to OpenBot: a key can never make another key, and neither can an app''s sign-in. A key ends when it expires, when it is deleted, or when an administrator removes the person.' + description: 'Make an API key that acts as the person, in every organization they are a member of, on the API. The key itself is in this answer and never again: OpenBot keeps only a hash of it. Only the person themselves may make one, signed in to OpenBot: a key can never make another key, and neither can an app''s sign-in. A key ends when it expires, when it is deleted, or when an administrator removes the person.' security: - webSession: [] parameters: @@ -1673,7 +1688,7 @@ paths: - Organization settings operationId: getDeployment summary: Read what this OpenBot offers - description: 'Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it first. It names no identity provider and no version: only whether single sign-on is set up and required.' + description: 'Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it first. Signed in, it is answered in an organization the caller is a member of, and an organization they are not in, the organization `default` included, answers exactly as one that does not exist. Nobody signed in reads it in the organization `default`. It names no identity provider and no version: only whether single sign-on is set up and required.' x-openbot-singleton: true security: - {} @@ -1704,7 +1719,7 @@ paths: - Organization settings operationId: getOrganizationSettings summary: Read the organization's settings - description: 'Return the settings an administrator sets for everybody: single sign-on, recording computer actions, stopping idle computers, the model and app allowlists, sharing learned skills, check-ins a day and choosing a model. Beside them, read only, what an administrator needs to set them: the model OpenBot runs on, the directory groups, the apps an allowlist can name, the hosts every computer may reach, and whether SCIM and OpenTelemetry are set up. Only an administrator may read them.' + description: 'Return the settings the organization''s administrators set for its members: single sign-on, recording computer actions, stopping idle computers, the model and app allowlists, sharing learned skills, check-ins a day and choosing a model. Each organization has its own, and a new one starts with OpenBot''s defaults. Beside them, read only, what an administrator needs to set them: the model OpenBot runs on, the directory groups of the organization''s members, the apps an allowlist can name, the hosts every computer may reach, and whether SCIM and OpenTelemetry are set up. Only an administrator of the organization may read them.' x-openbot-singleton: true security: - webSession: [] @@ -1739,7 +1754,7 @@ paths: - Organization settings operationId: updateOrganizationSettings summary: Change the organization's settings - description: Change the settings sent and keep the rest. Each change is recorded on the audit trail with what it was before. Requiring single sign-on needs an identity provider registered first, and signs out everybody who signed in another way, apart from the administrators the deployment's configuration names and the caller. Only an administrator may change them. + description: 'Change the settings sent and keep the rest. Each change is recorded on the audit trail with what it was before. Requiring single sign-on needs an identity provider registered first, and signs out everybody who signed in another way, apart from the administrators the deployment''s configuration names and the caller. Requiring single sign-on applies to signing in to the whole OpenBot, so it is set only in the organization `default`: sending ssoRequired in any other organization answers 409. Only an administrator of the organization may change them.' security: - webSession: [] - appOAuth: @@ -2099,7 +2114,7 @@ paths: - Capabilities operationId: getPersonCapabilities summary: Read what a person may do - description: Return each permission switch as it applies to one person, so the apps hide what they may not use. The caller reads their own, as me; an administrator reads anybody's. enforced is false where the deployment keeps no switches and every default applies. + description: Return each permission switch as it applies to one person, so the apps hide what they may not use. The caller reads their own, as me; an administrator of the organization reads any member's. enforced is false where this OpenBot keeps no switches and every default applies. x-openbot-singleton: true security: - webSession: [] @@ -2140,7 +2155,7 @@ paths: - Capabilities operationId: stopPersonComputers summary: Stop a person's computers - description: Stop every Bot computer running for one person now, and record it on the audit trail. Their Bots start a computer again when they next need one. Only an administrator may do this. + description: Stop the computers of the organization's Bots that one person owns, now, and record it on the audit trail. Their Bots start a computer again when they next need one. A person's own computer is stopped only from the organization `default`. A person who is not a member of the organization is not found (PERSON_NOT_FOUND). Only an administrator of the organization may do this. security: - webSession: [] - appOAuth: @@ -2421,7 +2436,7 @@ paths: - Organization settings operationId: getModelUsage summary: Read which models Bots ran on - description: Return which models Bots ran on over the last days, with how many runs, refusals and people each had, and the newest 50 runs. Only an administrator may read it. + description: Return which models the organization's Bots ran on over the last days, with how many runs, refusals and people each had, and the newest 50 runs. Only an administrator of the organization may read it. x-openbot-singleton: true security: - webSession: [] @@ -2470,7 +2485,7 @@ paths: - Organization settings operationId: listComputerActions summary: List recorded computer actions - description: Return one page of the actions recorded on Bot computers while recording computer actions is on, newest first. Records are kept for actionRecordRetentionDays. Only an administrator may read them. A missing cursor starts at the newest and nextCursor null ends the list. + description: Return one page of the actions recorded on the organization's Bots' computers while recording computer actions is on, newest first. Records are kept for actionRecordRetentionDays. Only an administrator of the organization may read them. A missing cursor starts at the newest and nextCursor null ends the list. security: - webSession: [] - appOAuth: @@ -2594,7 +2609,7 @@ paths: - Conversations operationId: createConversationJoinToken summary: Get a token to watch a conversation live - description: 'Make a join token for the conversation''s thread, and say where to use it. The token opens the threadStream channel of api/asyncapi.yaml: a WebSocket that replays the Bot''s runs in the conversation, a run in progress from its start, and then carries on live. The token works once and for about half a minute, so ask for a new one for every connection, and again to reconnect. Only a person in the conversation may have one, and it opens the thread they see there and no other. A conversation no Bot has run in yet has nothing to join.' + description: 'Make a join token for the conversation''s thread, and say where to use it. The token opens the threadStream channel of api/asyncapi.yaml: a WebSocket that replays the Bot''s runs in the conversation, a run in progress from its start, and then carries on live. The token works once and for about half a minute, so ask for a new one for every connection, and again to reconnect. Only a person in the conversation may have one, and it opens the thread they see there and no other. A conversation no Bot has run in yet has nothing to join (409). Where realtime.clientUrl is on this server, open it with the same credential that made the token: the session, an app''s access token, or an API key, as Authorization: Bearer or x-api-key. So a script that holds only an API key can watch a conversation live.' security: - webSession: [] - appOAuth: @@ -3945,7 +3960,7 @@ paths: - Credentials operationId: listCredentials summary: List the credentials in the vault - description: 'Return one page of the credentials the vault keeps, live and revoked, oldest first. A credential says what it is for and whether it is live, and never holds its secret: nothing in the API reads a secret back out. Only an administrator may list them. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the credentials the organization''s vault keeps, live and revoked, oldest first. Each organization has its own vault, and another organization''s credentials are never listed. A credential says what it is for and whether it is live, and never holds its secret: nothing in the API reads a secret back out. Only an administrator of the organization may list them. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -3986,7 +4001,7 @@ paths: - Credentials operationId: createCredential summary: Add a credential to the vault - description: 'Encrypt a secret and keep it in the vault under one key: a kind, a provider and a key id. A key holds one live credential, so adding one for a key that already has one replaces it, and the one it replaces is revoked in the same write. A model key sent without a key id is filed under the name OpenBot''s own Bots read (getModelKey). The secret is write-only: no answer includes it, now or later. Recorded on the audit trail. Only an administrator may add one.' + description: 'Encrypt a secret and keep it in the organization''s vault under one key: a kind, a provider and a key id. A key holds one live credential, so adding one for a key that already has one replaces it, and the one it replaces is revoked in the same write. A model key sent without a key id is filed under the name OpenBot''s own Bots read (getModelKey). The secret is write-only: no answer includes it, now or later. Recorded on the audit trail. Only an administrator of the organization may add one.' security: - webSession: [] - appOAuth: @@ -4044,7 +4059,7 @@ paths: - Credentials operationId: revokeCredential summary: Revoke a credential - description: Stop a live credential being used, and keep its record. Nothing reads a revoked credential again. Recorded on the audit trail. Only an administrator may revoke one. One that does not exist, or is revoked already, is not found. + description: Stop a live credential being used, and keep its record. Nothing reads a revoked credential again. Recorded on the audit trail. Only an administrator of the organization may revoke one. One that does not exist, is in another organization's vault, or is revoked already, is not found. security: - webSession: [] - appOAuth: @@ -4089,7 +4104,7 @@ paths: - Credentials operationId: getModelKey summary: Read where the Bots find their model key - description: Return the provider OpenBot's own Bots run on, the key id their model key is filed under in the vault, and whether a live key is kept there. Never the key. A model key added without a key id is filed here. Only an administrator may read it. + description: Return the provider OpenBot's own Bots run on, the key id their model key is filed under in the organization's vault, and whether a live key is kept there. Never the key. A model key added without a key id is filed here. Only an administrator of the organization may read it. x-openbot-singleton: true security: - webSession: [] @@ -4269,7 +4284,7 @@ paths: - Apps operationId: listApps summary: List the apps added here - description: 'Return one page of the apps this OpenBot has added for its Bots: the ones from its catalogue, the ones added from the app directory, and servers added by their address. Each app comes with the actions it offers and the Bots that may use each one. Anybody signed in may read them. Ordered by title, ignoring case, then by id. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the apps the organization has added for its Bots: the ones from OpenBot''s catalogue, the ones added from the app directory, and servers added by their address. Each organization has its own apps, and an app added in one is not in another. Each app comes with the actions it offers and the Bots that may use each one. Any member of the organization may read them. Ordered by title, ignoring case, then by id. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -4533,7 +4548,7 @@ paths: - Apps operationId: deleteApp summary: Remove an app - description: Remove an app for everybody. Every person's connection to it is ended, at the app's own service too, every Bot stops being able to use its actions, and a server's key is retired. Recorded on the audit trail. Removing can stop partway when the service behind the app doesn't answer. The app then stays, and removing it again is safe and finishes the job. Routines can't be removed. Only an administrator may. + description: Remove an app for everybody in the organization. Every member's connection to it is ended, at the app's own service too, every Bot stops being able to use its actions, and a server's key is retired. Recorded on the audit trail. Removing can stop partway when the service behind the app doesn't answer. The app then stays, and removing it again is safe and finishes the job. Routines can't be removed. Only an administrator of the organization may. security: - webSession: [] - appOAuth: @@ -4615,7 +4630,7 @@ paths: - Apps operationId: setAppAccountMode summary: Choose whose account an app acts in - description: 'Choose whose account an app from the directory acts in: each person''s own (personal), or one account OpenBot holds for everybody (shared). Every account the switch leaves behind is ended at the app''s service first. Nothing changes unless all of them ended, and the problem''s problems then names each account that didn''t. Switching to shared gives each Bot that uses the app an approval, the one in approvals or its default, and makes the app ask before every action that changes something. With validateOnly true nothing changes, and the answer says what the switch would end and approve. Choosing the mode an app is already in puts back anything that mode needs and is missing. Recorded on the audit trail. Only an administrator may.' + description: 'Choose whose account an app from the directory acts in: each person''s own (personal), or one account OpenBot holds for everybody in the organization (shared). Every account the switch leaves behind is ended at the app''s service first. Nothing changes unless all of them ended, and the problem''s problems then names each account that didn''t. Switching to shared gives each Bot that uses the app an approval, the one in approvals or its default, and makes the app ask before every action that changes something. With validateOnly true nothing changes, and the answer says what the switch would end and approve. Choosing the mode an app is already in puts back anything that mode needs and is missing. Recorded on the audit trail. Only an administrator may.' security: - webSession: [] - appOAuth: @@ -5463,7 +5478,7 @@ paths: - Connections operationId: getSharedConnection summary: Read an app's shared account - description: 'Return the one account an app in Shared mode acts as for everybody: whether it is connected, who connected it, and the app''s own name for the account. Anybody signed in may read it. Not found when the app is connected by each person instead, as getConnection reads.' + description: 'Return the one account an app in Shared mode acts as for everybody in the organization: whether it is connected, who connected it, and the app''s own name for the account. Each organization connects its own, and one organization''s shared account is never used in another. Any member of the organization may read it. Not found when the app is connected by each person instead, as getConnection reads.' x-openbot-singleton: true security: - webSession: [] @@ -5504,7 +5519,7 @@ paths: - Connections operationId: connectSharedApp summary: Start connecting an app's shared account - description: 'Start connecting the one account an app in Shared mode acts as for everybody, and say what happens next, as connectApp does: consent answers the address of the app''s sign-in page, form answers the boxes to fill in, connected means it is connected already. The person comes back to the app''s page, where confirmSharedConnection checks the result. Where an app connects once, a shared account already connected is a conflict: disconnect it first. Only an administrator may connect it. The address and the values are never logged.' + description: 'Start connecting the one account an app in Shared mode acts as for everybody in the organization, and say what happens next, as connectApp does: consent answers the address of the app''s sign-in page, form answers the boxes to fill in, connected means it is connected already. The person comes back to the app''s page, where confirmSharedConnection checks the result. Where an app connects once, a shared account already connected is a conflict: disconnect it first. Only an administrator of the organization may connect it. The address and the values are never logged.' security: - webSession: [] - appOAuth: @@ -6339,6 +6354,98 @@ paths: $ref: '#/components/responses/AppDirectoryUnavailable' default: $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/apps/{appId}/team-grants: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/AppId' + get: + tags: + - Bot grants + operationId: getAppTeamGrants + summary: Read the teams the app is granted to + description: Return the teams the app is granted to, by id. A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. Only an admin of the organization may read them. + x-openbot-singleton: true + security: + - webSession: [] + - appOAuth: + - bot-grants:read + - apiKey: [] + responses: + '200': + description: The teams the app is granted to. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/AppTeamGrants' + examples: + granted: + $ref: '#/components/examples/AppTeamGrantsExample' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/AppOrTeamNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + put: + tags: + - Bot grants + operationId: replaceAppTeamGrants + summary: Grant an app to teams + description: Grant the app to exactly these teams of the organization, taking it from any team left out. An empty list takes it from every team. A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. A team of another organization is not found. Only an admin of the organization may do this. Recorded on the audit trail. + security: + - webSession: [] + - appOAuth: + - bot-grants:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AppTeamGrantsInput' + examples: + oneTeam: + value: + teams: + - Tm4Qx8LpV2nWc7RbY1sKd0Ze + responses: + '200': + description: The teams the app is now granted to. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/AppTeamGrants' + examples: + granted: + $ref: '#/components/examples/AppTeamGrantsExample' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/AppOrTeamNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/people/{personId}/giveable-apps: parameters: - $ref: '#/components/parameters/OrganizationId' @@ -6390,7 +6497,7 @@ paths: - App access requests operationId: listAppAccessRequests summary: List requests for apps - description: 'Return one page of the requests waiting for an administrator: all of them for an administrator, and only their own for anybody else. appId narrows them to one app. Newest first, and by id among requests made at the same moment. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the organization''s requests waiting for an administrator: all of them for an administrator of the organization, and only their own for anybody else. appId narrows them to one app. Newest first, and by id among requests made at the same moment. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -6649,7 +6756,7 @@ paths: - Components operationId: listComponents summary: List components - description: 'Return one page of the components Bots draw in conversations: charts, cards and the ones an admin wrote in Playground. An admin sees every component with its draft, the Bots held back from it and the data it may read. Anybody else sees the published ones only, and those fields are null. kind=playground lists only the components written in Playground, each published one with the source a conversation draws it from. Ordered by kind, then title, then name. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the components the organization''s Bots draw in conversations: charts, cards and the ones an admin wrote in Playground. Each organization has its own: what a component tells the model, whether it is published, which Bots may draw it and which data it may read are decided in one organization and change nothing in another. An admin of the organization sees every component with its draft, the Bots held back from it and the data it may read. Anybody else sees the published ones only, and those fields are null. kind=playground lists only the components written in Playground, each published one with the source a conversation draws it from. Ordered by kind, then title, then name. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -6692,7 +6799,7 @@ paths: - Components operationId: announceComponents summary: Announce the components the app can draw - description: 'Tell OpenBot which components this version of the app can draw. A component OpenBot has not seen before is added and published, so every Bot can draw it at once. One it already has is left exactly as it is: what it tells the model, whether it is published and who may use it were decided here. A description nobody here has edited follows the one this version of OpenBot ships. In OpenBot Personal a component is also given the data it reads. Anybody signed in may announce, and the web app does it on every load. The whole list is refused if one entry is missing a field.' + description: 'Tell OpenBot which components this version of the app can draw. A component the organization has not seen before is added and published, so every one of its Bots can draw it at once. One it already has is left exactly as it is: what it tells the model, whether it is published and who may use it were decided here. A description nobody here has edited follows the one this version of OpenBot ships. In OpenBot Personal a component is also given the data it reads. Anybody signed in may announce, and the web app does it on every load. The whole list is refused if one entry is missing a field or has a name that starts with @.' security: - webSession: [] - appOAuth: @@ -6720,7 +6827,7 @@ paths: description: Show how many actions each Bot took recently. responses: '200': - description: The components this announcement added. Empty when OpenBot had them all. + description: The components this announcement added. Empty when the organization had them all. headers: Cache-Control: $ref: '#/components/headers/PrivateNoStore' @@ -7335,7 +7442,7 @@ paths: - Skills operationId: listSkills summary: List skills - description: 'Return one page of the skills the caller can see: the organization''s and their own. An admin sees everybody''s. Ordered by title, then slug. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the skills the caller can see: their own, the ones granted to a team they are in, and the organization''s that are granted to no team. An organization''s skill granted to teams is listed only to those teams'' people. An admin of the organization sees every skill. Another organization''s skills are never listed. Ordered by title, then slug. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -7378,7 +7485,7 @@ paths: - Skills operationId: getSkill summary: Read a skill - description: 'Return one skill the caller can see: the organization''s or their own. An admin can read anybody''s. Somebody else''s skill is not found.' + description: Return one skill the caller can see, as the list shows them. An admin can read any. One the caller can't see is not found. security: - webSession: [] - appOAuth: @@ -7493,6 +7600,98 @@ paths: $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/skills/{skillId}/team-grants: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/SkillId' + get: + tags: + - Skills + operationId: getSkillTeamGrants + summary: Read the teams the skill is granted to + description: Return the teams the skill is granted to, by id. A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. Only an admin of the organization may read them. + x-openbot-singleton: true + security: + - webSession: [] + - appOAuth: + - skills:read + - apiKey: [] + responses: + '200': + description: The teams the skill is granted to. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/SkillTeamGrants' + examples: + granted: + $ref: '#/components/examples/SkillTeamGrantsExample' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/SkillOrTeamNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + put: + tags: + - Skills + operationId: replaceSkillTeamGrants + summary: Grant a skill to teams + description: Grant the skill to exactly these teams of the organization, taking it from any team left out. An empty list takes it from every team. A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. A team of another organization is not found. Only an admin of the organization may do this. Recorded on the audit trail. + security: + - webSession: [] + - appOAuth: + - skills:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SkillTeamGrantsInput' + examples: + oneTeam: + value: + teams: + - Tm4Qx8LpV2nWc7RbY1sKd0Ze + responses: + '200': + description: The teams the skill is now granted to. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/SkillTeamGrants' + examples: + granted: + $ref: '#/components/examples/SkillTeamGrantsExample' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/SkillOrTeamNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/people/{personId}/devices: parameters: - $ref: '#/components/parameters/OrganizationId' @@ -7632,7 +7831,7 @@ paths: - Destinations operationId: listDestinations summary: List where a person's Bots reach them - description: 'Return one page of the places outside OpenBot a person continues their conversations with Bots: a Slack or Microsoft Teams chat, or a phone number for text messages, each tied to one conversation with one Bot. The first connected first. Only the person themselves may list them; there is no administrator view. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the places outside OpenBot a person continues their conversations with Bots: a Slack or Microsoft Teams chat, or a phone number for text messages, each tied to one conversation with one Bot. A Slack account, a Teams account or a phone number is connected in one organization at a time: connecting one that is connected in another organization answers 400 until it is disconnected there. The first connected first. Only the person themselves may list them; there is no administrator view. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -8817,7 +9016,7 @@ paths: - Check-ins operationId: getCheckInUsage summary: Read how check-ins are going - description: 'Return, per Bot, over the last 7 or 30 days: how its check-ins ended, what they raised, what people did with it and how many notices carried it, with the daily limit in force. Counts only: no item''s title, source or person. Only an administrator may read it.' + description: 'Return, per Bot in the organization, over the last 7 or 30 days: how its check-ins ended, what they raised, what people did with it and how many notices carried it, with the organization''s daily limit in force. Counts only: no item''s title, source or person. Only an administrator of the organization may read it.' x-openbot-singleton: true security: - webSession: [] @@ -9809,7 +10008,7 @@ paths: - Organizations operationId: listOrganizations summary: List the caller's organizations - description: Return one page of the organizations the caller is a member of, the one they joined first at the top, each with the caller's role in it. active marks the one the caller's session is working in, which is where every address outside /api/v2 reads and writes; a request signed in with an API key or an app's token has no session, so none is active. To work in another one, set it as the session's active organization (POST /api/auth/organization/set-active). A missing cursor starts at the first page and nextCursor null ends the list. + description: 'Return one page of the organizations the caller is a member of, the one they joined first at the top, each with the caller''s role in it. active marks the one the caller''s session is working in, which is where every address outside /api/v2 reads and writes. A request signed in with an API key has no session, so none is active. An app''s token has no session either: for it, active marks the organization its OpenBot-Organization header names, or the caller''s own when it sends none. The header is checked against the caller''s membership, as on every address that names no organization, so one they are not in answers not found. A session and an API key ignore it. To work in another one, set it as the session''s active organization (POST /api/auth/organization/set-active). Made with an app''s token, that call checks that the caller is a member, stores nothing and answers the organization. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -9818,6 +10017,14 @@ paths: parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Cursor' + - name: OpenBot-Organization + in: header + required: false + description: 'For a request signed in with an app''s token: the organization it works in, by id or slug, which the list marks active. Without it the caller''s own is active. One the caller is not a member of answers not found, and one that is not a single id or slug 400. Ignored for a session and an API key.' + schema: + type: string + minLength: 1 + maxLength: 200 responses: '200': description: One page of organizations. @@ -9837,6 +10044,8 @@ paths: $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/OrganizationNotFound' '500': $ref: '#/components/responses/ServerError' default: @@ -9846,7 +10055,7 @@ paths: - Organizations operationId: createOrganization summary: Create an organization - description: 'Create an organization with the caller as its owner. It starts with no Bots and no conversations. Who may create one is the deployment''s choice: its admins (the admins of `default`) unless it lets anybody signed in. Without a slug, one is made from the name. The caller''s session keeps working where it was. A repeated request with the same Idempotency-Key and body returns the first result.' + description: Create an organization with the caller as its owner. It starts with what a fresh install starts with, its starter Bots included, and no conversations. Everybody already has an organization of their own, made when they first signed in; this is for making another, which anybody signed in may do where OpenBot keeps more than one. Without a slug, one is made from the name. The caller's session keeps working where it was. A repeated request with the same Idempotency-Key and body returns the first result. security: - webSession: [] - appOAuth: @@ -9883,7 +10092,7 @@ paths: '401': $ref: '#/components/responses/Unauthenticated' '403': - $ref: '#/components/responses/AdminOnly' + $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/OrganizationConflict' '500': @@ -9934,12 +10143,194 @@ paths: $ref: '#/components/responses/ServerError' default: $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/profile: + parameters: + - $ref: '#/components/parameters/OrganizationId' + patch: + tags: + - Organizations + operationId: updateOrganization + summary: Rename an organization + description: Give the organization a new name. Its id and its slug stay as they are, so every address that names it keeps working. An organization OpenBot named after its person stops following what that person is called once it has been renamed. Only an owner or an admin of this organization can. A repeated request with the same Idempotency-Key and body returns the first result. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationRequest' + examples: + renamed: + value: + name: Acme Research Lab + responses: + '200': + description: The organization, renamed. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationResponse' + examples: + renamed: + $ref: '#/components/examples/RenamedOrganization' + '400': + $ref: '#/components/responses/InvalidOrganization' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/members/{personId}: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/PersonId' + patch: + tags: + - Organizations + operationId: updateOrganizationMember + summary: Change a member's role + description: 'Give a member of the organization another role. An owner or an admin changes anybody between admin and member. Only an owner makes somebody an owner, or changes an owner''s role, their own included, and the organization always keeps an owner: the last one cannot step down. A person''s own organization keeps exactly its one owner. The members list says which roles the caller may give each member, as assignableRoles. A repeated request with the same Idempotency-Key and body returns the first result.' + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationMemberRequest' + examples: + owner: + value: + role: owner + responses: + '200': + description: The member, with their new role. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationMemberResponse' + examples: + owner: + $ref: '#/components/examples/PromotedOrganizationMember' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/PersonNotFound' + '409': + $ref: '#/components/responses/OwnerStays' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + delete: + tags: + - Organizations + operationId: removeOrganizationMember + summary: Remove a member, or leave an organization + description: End somebody's membership of the organization. An owner or an admin of it can remove anybody whose membership can end, and any such member can leave by naming themselves or `me`. The owner stays, so nobody leaves their own organization, and so does somebody this OpenBot's settings keep as an admin of it. The person keeps their account and their other organizations, and what they made here stays here. Removing somebody who is not a member answers the same as removing one. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '204': + description: They are not a member. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/OwnerStays' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/invitations: + parameters: + - $ref: '#/components/parameters/OrganizationId' + get: + tags: + - Organizations + operationId: listOrganizationInvitations + summary: List the invitations an organization has sent + description: 'Return one page of the organization''s invitations that have not been accepted or canceled, the newest first: the ones still waiting, the ones that expired and the ones that were declined. Only an owner or an admin of this organization can read it. A missing cursor starts at the first page and nextCursor null ends the list.' + security: + - webSession: [] + - appOAuth: + - organizations:read + - apiKey: [] + parameters: + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Cursor' + responses: + '200': + description: One page of invitations. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationInvitationPage' + examples: + lastPage: + $ref: '#/components/examples/OrganizationInvitationPageLast' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' post: tags: - Organizations - operationId: addOrganizationMember - summary: Add a person to an organization - description: Make somebody who already has an account here a member of the organization, by their email address, with a role. Only an owner or an admin of this organization can. A repeated request with the same Idempotency-Key and body returns the first result. + operationId: createOrganizationInvitation + summary: Invite somebody to an organization + description: 'Invite the person with this email address to join the organization with a role. They need no account yet: the invitation waits for whoever signs in with that address, and they see it in OpenBot then. Where OpenBot can send email, it also emails them; delivery says which happened, so the inviter knows whether to pass the link on themselves. The invitation lasts seven days. Inviting an address again after its invitation expired or was declined starts a new one. Only an owner or an admin of this organization can. A repeated request with the same Idempotency-Key and body returns the first result.' security: - webSession: [] - appOAuth: @@ -9952,7 +10343,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/AddOrganizationMemberRequest' + $ref: '#/components/schemas/CreateOrganizationInvitationRequest' examples: member: value: @@ -9960,32 +10351,567 @@ paths: role: member responses: '201': - description: The person is now a member. + description: The invitation was made. headers: Cache-Control: $ref: '#/components/headers/PrivateNoStore' Location: - description: The organization's members. + description: The organization's invitations. schema: type: string - example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/members + example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/invitations content: application/json: schema: - $ref: '#/components/schemas/OrganizationMemberResponse' + $ref: '#/components/schemas/OrganizationInvitationResponse' examples: - added: - $ref: '#/components/examples/AddedOrganizationMember' + invited: + $ref: '#/components/examples/CreatedOrganizationInvitation' + '400': + $ref: '#/components/responses/InvalidOrganizationInvitation' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/OrganizationInvitationConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/invitations/{invitationId}: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/InvitationId' + delete: + tags: + - Organizations + operationId: cancelOrganizationInvitation + summary: Cancel an invitation + description: Take back an invitation the organization sent, whatever state it is in. It leaves the organization's list and the invited person's. Only an owner or an admin of this organization can. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '204': + description: The invitation is canceled. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/OrganizationOrInvitationNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/people/me/invitations: + get: + tags: + - Organizations + operationId: listInvitations + summary: List the caller's invitations + description: Return one page of the invitations sent to the caller's email address that they have not answered, the newest first, each with the organization and who invited them. One that ran out of time is listed as expired until it is canceled or replaced. A missing cursor starts at the first page and nextCursor null ends the list. + security: + - webSession: [] + - appOAuth: + - organizations:read + - apiKey: [] + parameters: + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Cursor' + responses: + '200': + description: One page of invitations. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/InvitationPage' + examples: + lastPage: + $ref: '#/components/examples/InvitationPageLast' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/people/me/invitations/{invitationId}: + parameters: + - $ref: '#/components/parameters/InvitationId' + get: + tags: + - Organizations + operationId: getInvitation + summary: Read one of the caller's invitations + description: Return an invitation sent to the caller's email address, in whatever state it is in, so the page a link opens can say what happened to it. An invitation sent to another address answers as one that does not exist. + security: + - webSession: [] + - appOAuth: + - organizations:read + - apiKey: [] + responses: + '200': + description: The invitation. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/InvitationResponse' + examples: + waiting: + $ref: '#/components/examples/WaitingInvitation' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/InvitationNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/people/me/invitations/{invitationId}/accept: + parameters: + - $ref: '#/components/parameters/InvitationId' + post: + tags: + - Organizations + operationId: acceptInvitation + summary: Accept an invitation + description: Join the organization the invitation is for, with the role it offers. The caller's session keeps working where it was; switch to the new organization to work in it. An invitation that expired, was canceled or was already answered is refused in words. A repeated request with the same Idempotency-Key returns the first result. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '200': + description: The caller is now a member of the organization. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationResponse' + examples: + joined: + $ref: '#/components/examples/JoinedOrganization' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/InvitationNotFound' + '409': + $ref: '#/components/responses/InvitationNotWaiting' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/people/me/invitations/{invitationId}/decline: + parameters: + - $ref: '#/components/parameters/InvitationId' + post: + tags: + - Organizations + operationId: declineInvitation + summary: Decline an invitation + description: Turn the invitation down. It leaves the caller's list, and the organization sees that it was declined. A repeated request with the same Idempotency-Key returns the first result. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '204': + description: The invitation is declined. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/InvitationNotFound' + '409': + $ref: '#/components/responses/InvitationNotWaiting' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams: + parameters: + - $ref: '#/components/parameters/OrganizationId' + get: + tags: + - Teams + operationId: listTeams + summary: List an organization's teams + description: Return one page of the organization's teams, in the order they were created. Any member of the organization can read it. Each team says the caller's own role in it and whether the caller may manage it. A missing cursor starts at the first page and nextCursor null ends the list. + security: + - webSession: [] + - appOAuth: + - organizations:read + - apiKey: [] + parameters: + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Cursor' + responses: + '200': + description: One page of teams. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamPage' + examples: + lastPage: + $ref: '#/components/examples/TeamPageLast' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + post: + tags: + - Teams + operationId: createTeam + summary: Create a team + description: Create a team in the organization. Only an owner or an admin of the organization can. A team's name is unique in its organization, whatever its case. A team may sit under a parent team, and then its members can use everything granted to the parent as well. A repeated request with the same Idempotency-Key and body returns the first result. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTeamRequest' + examples: + named: + value: + name: Sales + description: Everybody who sells. + responses: + '201': + description: The team was created. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + Location: + description: The new team. + schema: + type: string + example: /api/v2/organizations/default/teams/Tm4Qx8LpV2nWc7RbY1sKd0Ze + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + examples: + created: + $ref: '#/components/examples/CreatedTeam' '400': - $ref: '#/components/responses/InvalidOrganizationMember' + $ref: '#/components/responses/InvalidTeam' '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/AdminOnly' '404': - $ref: '#/components/responses/OrganizationOrPersonNotFound' + $ref: '#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/TeamConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams/{teamId}: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TeamId' + get: + tags: + - Teams + operationId: getTeam + summary: Read one team + description: Return one of the organization's teams. Any member of the organization can read it. A team of another organization is not found. + security: + - webSession: [] + - appOAuth: + - organizations:read + - apiKey: [] + responses: + '200': + description: The team. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + examples: + team: + $ref: '#/components/examples/CreatedTeam' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + patch: + tags: + - Teams + operationId: updateTeam + summary: Change a team + description: Change a team's name, its description or its parent team; a field that is absent stays as it is, and a null parent takes the team out from under its parent. An owner or an admin of the organization can, and so can one of the team's maintainers, except that only an owner or an admin changes its parent. A team that comes from the company's directory keeps the directory's name. A team can't be put under itself or under a team beneath it. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTeamRequest' + examples: + renamed: + value: + name: Sales EMEA + responses: + '200': + description: The team as it now is. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + examples: + changed: + $ref: '#/components/examples/CreatedTeam' + '400': + $ref: '#/components/responses/InvalidTeam' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '409': + $ref: '#/components/responses/TeamConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + delete: + tags: + - Teams + operationId: deleteTeam + summary: Delete a team + description: Delete a team. Its members stay in the organization and lose what was granted to the team, at once. Teams under it move up to its own parent. Only an owner or an admin of the organization can. A team that comes from the company's directory is removed there, not here. Deleting a team that is not there changes nothing. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '204': + description: The team is gone. + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams/{teamId}/members: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TeamId' + get: + tags: + - Teams + operationId: listTeamMembers + summary: List a team's members + description: Return one page of the people in a team, in the order they joined it. Any member of the organization can read it. People who are only in a team beneath this one are not listed. A missing cursor starts at the first page and nextCursor null ends the list. + security: + - webSession: [] + - appOAuth: + - organizations:read + - apiKey: [] + parameters: + - $ref: '#/components/parameters/Limit' + - $ref: '#/components/parameters/Cursor' + responses: + '200': + description: One page of the team's members. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamMemberPage' + examples: + lastPage: + $ref: '#/components/examples/TeamMemberPageLast' + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams/{teamId}/members/{memberId}: + parameters: + - $ref: '#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TeamId' + - $ref: '#/components/parameters/TeamMemberId' + put: + tags: + - Teams + operationId: putTeamMember + summary: Add a person to a team, or change their role in it + description: Put a member of the organization in the team with a role, or change the role of somebody already in it. What is granted to the team is theirs from their next request. An owner or an admin of the organization can, and so can one of the team's maintainers. A team that comes from the company's directory takes its people from the directory, so nobody is added to it here. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PutTeamMemberRequest' + examples: + member: + value: + role: member + responses: + '200': + description: The person as a member of the team. + headers: + Cache-Control: + $ref: '#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamMemberResponse' + examples: + added: + $ref: '#/components/examples/AddedTeamMember' + '400': + $ref: '#/components/responses/InvalidTeamMember' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/TeamOrPersonNotFound' + '409': + $ref: '#/components/responses/IdempotencyConflict' + '500': + $ref: '#/components/responses/ServerError' + default: + $ref: '#/components/responses/UnexpectedError' + delete: + tags: + - Teams + operationId: removeTeamMember + summary: Take a person out of a team + description: Take a person out of the team. They stay in the organization and lose what was granted to the team from their next request. An owner or an admin of the organization can, so can one of the team's maintainers, and anybody can take themselves out. A team that comes from the company's directory takes its people from the directory, so nobody is removed from it here. Removing somebody who is not in the team changes nothing. + security: + - webSession: [] + - appOAuth: + - organizations:write + - apiKey: [] + parameters: + - $ref: '#/components/parameters/IdempotencyKey' + responses: + '204': + description: They are not in the team. + '400': + $ref: '#/components/responses/InvalidRequest' + '401': + $ref: '#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/TeamNotFound' '409': - $ref: '#/components/responses/OrganizationMemberConflict' + $ref: '#/components/responses/IdempotencyConflict' '500': $ref: '#/components/responses/ServerError' default: @@ -13007,7 +13933,7 @@ paths: - Team Bots operationId: listTeamBots summary: List Team Bots - description: 'Return one page of the published Bots the caller may use or manages: their own publications, the ones published to them by name, to a group they are in or to the whole team, and the ones an administrator assigned them. An administrator sees every one. Who a Team Bot reaches (people, groups and assignments) is shown only to its owner and administrators. Ordered by name, then the Bot''s id. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the published Bots the caller may use or manages: their own publications, the ones published to them by name, to a group or team they are in or to everyone in the organization, and the ones an administrator assigned them. An administrator sees every one. Who a Team Bot reaches (people, groups and assignments) is shown only to its owner and administrators. Ordered by name, then the Bot''s id. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -13085,8 +14011,8 @@ paths: tags: - Team Bots operationId: publishTeamBot - summary: Publish a Bot to the team - description: Publish one of the caller's own Bots to the whole team, or to named people and directory groups, or change who it is published to. Each person's conversations with it are private to them; its owner can't read them. Needs the caller's Team Bots switch, and a Bot with a real name and a description, which is how teammates tell it apart. Every person named must have signed in here. Publishing can widen who reaches the shared app accounts the Bot uses, and the answer says which an administrator still has to approve. + summary: Publish a Bot to everyone in the organization, or to some of them + description: Publish one of the caller's own Bots to everyone in the organization, or to named people, teams and directory groups, or change who it is published to. Each person's conversations with it are private to them; its owner can't read them. Needs the caller's Team Bots switch, and a Bot with a real name and a description, which is how the people it is published to tell it apart. Every person named must have signed in here. Publishing can widen who reaches the shared app accounts the Bot uses, and the answer says which an administrator still has to approve. security: - webSession: [] - appOAuth: @@ -13102,7 +14028,7 @@ paths: $ref: '#/components/schemas/TeamBotPublication' examples: team: - summary: To the whole team. + summary: To everyone in the organization. value: audience: team people: @@ -13145,7 +14071,7 @@ paths: - Team Bots operationId: unpublishTeamBot summary: Unpublish a Team Bot - description: 'Stop publishing a Bot: teammates can''t use it until it is published again, and its assignments wait, doing nothing. Its owner or an administrator may unpublish it. Unpublishing a Bot that is not published changes nothing.' + description: 'Stop publishing a Bot: the people it was published to can''t use it until it is published again, and its assignments wait, doing nothing. Its owner or an administrator may unpublish it. Unpublishing a Bot that is not published changes nothing.' security: - webSession: [] - appOAuth: @@ -13332,7 +14258,7 @@ paths: - Computers operationId: listComputers summary: List the organization's computers - description: 'Return one page of the computers Bots run on: each person''s, and each isolated Bot''s. Where every person''s Bots share one computer, each entry is one person''s seat on one Bot there. Ordered by whose computer it is, then by Bot. Only an administrator may read them. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of the computers the organization''s Bots run on: each person''s, and each isolated Bot''s. Where every person''s Bots share one computer, each entry is one person''s seat on one Bot there. A computer another organization''s Bots run on is never listed. Ordered by whose computer it is, then by Bot. Only an administrator of the organization may read them. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -13376,7 +14302,7 @@ paths: - Computers operationId: stopComputer summary: Stop a computer - description: Stop one computer from the list now, and record it on the audit trail. Its files and sign-ins stay, and it starts again when a Bot next needs it. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. Only an administrator may do this. + description: Stop one computer from the list now, and record it on the audit trail. Its files and sign-ins stay, and it starts again when a Bot next needs it. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. A computer that is not one of the organization's is not found. Only an administrator of the organization may do this. security: - webSession: [] - appOAuth: @@ -13414,7 +14340,7 @@ paths: '403': $ref: '#/components/responses/AdminOnly' '404': - $ref: '#/components/responses/OrganizationNotFound' + $ref: '#/components/responses/OrganizationComputerNotFound' '409': $ref: '#/components/responses/IdempotencyConflict' '500': @@ -13431,7 +14357,7 @@ paths: - Computers operationId: resetComputer summary: Reset a computer - description: Delete one computer's browser profile, and every sign-in with it, and record it on the audit trail. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. Only an administrator may do this. + description: Delete one computer's browser profile, and every sign-in with it, and record it on the audit trail. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared computer. A computer that is not one of the organization's is not found. Only an administrator of the organization may do this. security: - webSession: [] - appOAuth: @@ -13469,7 +14395,7 @@ paths: '403': $ref: '#/components/responses/AdminOnly' '404': - $ref: '#/components/responses/OrganizationNotFound' + $ref: '#/components/responses/OrganizationComputerNotFound' '409': $ref: '#/components/responses/IdempotencyConflict' '500': @@ -13486,7 +14412,7 @@ paths: - Computers operationId: updateComputer summary: Update a computer - description: Move one computer onto the image this OpenBot now runs, and record it on the audit trail. Files and sign-ins stay; a running computer restarts. The computer is named by whose it is, person: or bot:. Only an administrator may do this. + description: Move one computer onto the image this OpenBot now runs, and record it on the audit trail. Files and sign-ins stay; a running computer restarts. The computer is named by whose it is, person: or bot:. A computer that is not one of the organization's is not found. Only an administrator of the organization may do this. security: - webSession: [] - appOAuth: @@ -13524,7 +14450,7 @@ paths: '403': $ref: '#/components/responses/AdminOnly' '404': - $ref: '#/components/responses/OrganizationNotFound' + $ref: '#/components/responses/OrganizationComputerNotFound' '409': $ref: '#/components/responses/IdempotencyConflict' '500': @@ -15646,7 +16572,7 @@ paths: - Sign-in requests operationId: getSignInRequest summary: Read a sign-in request - description: 'Return one sign-in request as its private form shows it: where it has got to, the last thing that happened, and the usernames of the person''s saved logins for that site while the password manager is on. Never a credential. Only the person it was opened for may read it; anybody else''s is not found.' + description: 'Return one sign-in request as its private form shows it: where it has got to, the last thing that happened, and the usernames of the person''s saved logins for that site while the password manager is on. Never a credential. Only the person it was opened for may read it; anybody else''s is not found. A request belongs to the organization the Bot asked in, and is not found in any other, so the link a Bot hands the person (/sign-in/{signInRequestId}) opens only while they are working in that organization.' security: - webSession: [] - appOAuth: @@ -16299,7 +17225,7 @@ paths: - Recorder operationId: deleteCurrentRecorderConnection summary: Disconnect this browser's Recorder - description: 'End the connection the request is signed with: the Recorder''s own Disconnect. Signed with the Recorder''s connection token and nothing else.' + description: 'End the connection the request is signed with: the Recorder''s own Disconnect. Signed with the Recorder''s connection token and nothing else. organizationId is `default` or the connection''s own organization, and either way the call acts in the connection''s organization.' security: - recorderConnection: [] parameters: @@ -16331,7 +17257,7 @@ paths: - Recorder operationId: getRecorderIdentity summary: Read who a Recorder is connected as - description: Return the person this Recorder's connection acts as, and the connection's id. Signed with the Recorder's connection token and nothing else. A connection that has ended is refused as signed out, with why. + description: Return the person this Recorder's connection acts as, and the connection's id. Signed with the Recorder's connection token and nothing else. organizationId is `default` or the connection's own organization, and either way the answer is for the connection's organization. A connection that has ended is refused as signed out, with why. x-openbot-singleton: true security: - recorderConnection: [] @@ -16368,7 +17294,7 @@ paths: - Recorder operationId: getRecorderLearning summary: Read where a Recorder's recordings are learned from - description: Return whether the recordings this Recorder's person makes land in their own Learning space, which is made on first need. Signed with the Recorder's connection token and nothing else. + description: Return whether the recordings this Recorder's person makes land in their own Learning space, which is made on first need. Signed with the Recorder's connection token and nothing else. organizationId is `default` or the connection's own organization, and either way the answer is for the connection's organization. x-openbot-singleton: true security: - recorderConnection: [] @@ -16405,7 +17331,7 @@ paths: - Recorder operationId: reportRecorderActivity summary: Say what a Recorder is doing now - description: 'Report what this browser''s Recorder is doing, which it says whenever its recording phase changes and every 30 seconds while a recording runs, so OpenBot can show a recording wherever the person made it. Kept against the connection in place of the last report, and never audited: it is a heartbeat. Signed with the Recorder''s connection token and nothing else.' + description: 'Report what this browser''s Recorder is doing, which it says whenever its recording phase changes and every 30 seconds while a recording runs, so OpenBot can show a recording wherever the person made it. Kept against the connection in place of the last report, and never audited: it is a heartbeat. Signed with the Recorder''s connection token and nothing else. organizationId is `default` or the connection''s own organization, and either way the report is kept in the connection''s organization.' security: - recorderConnection: [] parameters: @@ -18029,7 +18955,7 @@ paths: - Memory operationId: listMemories summary: List a person's memories - description: 'Return one page of what a person''s Bots remember about them, most recently changed first: the ones they wrote, the ones their Bots formed and are waiting for their review, the ones read in from their sources, and the ones the backend holds for them that OpenBot formed no record of, after OpenBot''s own. Paused memories are included; forgotten ones are not. Only the person themselves may list them: an administrator can''t either. A missing cursor starts at the first page and nextCursor null ends the list.' + description: 'Return one page of what a person''s Bots remember about them in this organization, and in no other they belong to, most recently changed first: the ones they wrote, the ones their Bots formed and are waiting for their review, the ones read in from their sources, and the ones the backend holds for them that OpenBot formed no record of, after OpenBot''s own. Paused memories are included; forgotten ones are not. Only the person themselves may list them: an administrator can''t either. A missing cursor starts at the first page and nextCursor null ends the list.' security: - webSession: [] - appOAuth: @@ -18484,7 +19410,22 @@ components: description: The web app's server-side session, so no token ever reaches the browser. Served over HTTPS the cookie is __Secure-better-auth.session_token. A single-user install signs its one person in without a cookie. appOAuth: type: oauth2 - description: Desktop and mobile. OAuth 2.1 authorization code with PKCE (RFC 7636, S256 only); the access token is sent as a bearer token. + description: |- + Desktop and mobile. OAuth 2.1 authorization code with PKCE (RFC 7636, S256 only); the access token is sent as a bearer token. + + Clients. Three public clients are registered: `openbot-desktop-oauth`, `openbot-mobile` and `openbot-cli`. A public client has no secret and must use PKCE with S256. Dynamic client registration is off, so an app uses one of these ids. + + Redirect addresses. A client on the person's own computer listens on a loopback address and any port: `http://127.0.0.1:/callback` or `http://[::1]:/callback`. `localhost` is not accepted. + + Endpoints. The authorization server's metadata (RFC 8414) is at `/.well-known/oauth-authorization-server/api/auth`. The person is sent to `/api/auth/oauth2/authorize`. The code is exchanged, and a token refreshed, at `/api/auth/oauth2/token`, with a form-encoded body (`application/x-www-form-urlencoded`) that carries `client_id` and no secret: the token and revocation endpoints take no client authentication (`none` in the metadata's `token_endpoint_auth_methods_supported`). A wrong `code_verifier` is answered 400 `invalid_grant`, and the code cannot be used again. A token is revoked (RFC 7009) at `/api/auth/oauth2/revoke`; revoking a token the server does not know, or one already revoked, answers 200. + + Tokens. An access token starts `oba_` and lasts one hour. A refresh token starts `obr_`, is issued only when the `offline_access` scope is asked for, and rotates on every use: each refresh answers a new refresh token and ends the one it was given. Access tokens work on /api/v2, and on four addresses outside it that an app's screens need, each with the scope given: `GET /api/me`, who is signed in (people:read); the chat runtime at `/api/copilotkit` and everything under it (conversations:write); a file's download at `GET /api/attachments/{attachmentId}`, the address a sent message keeps (conversations:read); and the relayed realtime socket at `/api/intelligence/client/websocket` (conversations:read). They work nowhere else. + + Organization. An access token carries no memory of which organization the person is working in. An address under `/api/v2/organizations/{organizationId}` names it. Where an address names none, such as the list of the person's own organizations, an app sends the header `OpenBot-Organization` with the organization's id. It is checked against the person's membership on every request, and an organization they are not in answers not found. With no header, the app works in the person's own organization. + + Consent. The person is asked once for each app, and not again for scopes they already allowed it. + + An install for one person on one computer has no sign-in, so it has no OAuth: there is nobody to authorize an app as. flows: authorizationCode: authorizationUrl: /api/auth/oauth2/authorize @@ -18523,7 +19464,7 @@ components: model-catalogue:read: Read the models Bots can run on. model-choices:read: Read the model the signed-in person chose for each of their conversations. model-choices:write: Choose the model the signed-in person's conversations answer on. - apps:read: Read the apps this OpenBot has added, the directory of apps it can add, and how apps are set up here. + apps:read: Read the apps the organization has added, the directory of apps it can add, and how apps are set up here. apps:write: Add, change, refresh and remove apps, when the signed-in person may. connections:read: Read the signed-in person's connections to apps, and each app's shared account. connections:write: Connect and disconnect the signed-in person's apps, and an app's shared account when the signed-in person is an administrator. @@ -18574,7 +19515,7 @@ components: type: http scheme: bearer bearerFormat: OpenBot API key - description: Automation. An API key acts as the person who created it, inside one organization. + description: 'Automation. An API key acts as the person who created it, in every organization they are a member of, like a personal access token: the address of each request names the organization, and one the person is not in answers not found. A key starts `obk_` and is sent as `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2 and on the relayed realtime socket at `/api/intelligence/client/websocket`, where a join token the key made is spent (createConversationJoinToken). A person makes one in the web app, signed in, under Settings, then API keys (createApiKey).' recorderConnection: type: http scheme: bearer @@ -18585,7 +19526,7 @@ components: name: organizationId in: path required: true - description: The organization, by its id or its slug. Every install has one addressed as `default`. + description: The organization, by its id or its slug. One the caller is not a member of answers as one that does not exist, `default` included. schema: type: string minLength: 1 @@ -18652,12 +19593,12 @@ components: name: networkPolicyId in: path required: true - description: organization, or group: for a directory group's. + description: organization, team: for a team's, or group: for a directory group's. schema: type: string minLength: 1 maxLength: 206 - pattern: ^(organization|group:[^\x00]*\S[^\x00]*)$ + pattern: ^(organization|team:[^\x00]*\S[^\x00]*|group:[^\x00]*\S[^\x00]*)$ BotId: name: botId in: path @@ -18709,7 +19650,7 @@ components: AuditEventTypes: name: eventType in: query - description: Events of any of these types, separated by commas, such as computer.action_refused,mcp.call_rejected. + description: Events of any of these types, separated by commas, such as computer.action_refused,mcp.call_rejected or organization.member_invited,organization.member_removed. schema: $ref: '#/components/schemas/AuditFilterText' AuditExcludedEventTypes: @@ -19018,6 +19959,38 @@ components: minLength: 1 maxLength: 200 pattern: \S + InvitationId: + name: invitationId + in: path + required: true + description: The invitation's id. Opaque. + schema: + type: string + minLength: 1 + maxLength: 128 + pattern: ^[A-Za-z0-9_-]+$ + TeamId: + name: teamId + in: path + required: true + description: The team's id. Opaque. + schema: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + example: Tm4Qx8LpV2nWc7RbY1sKd0Ze + TeamMemberId: + name: memberId + in: path + required: true + description: The person's id, or me for the caller. + schema: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + example: 2fn8w1c6y4tq7h0mbe3s ApprovalId: name: approvalId in: path @@ -19113,7 +20086,7 @@ components: name: group in: path required: true - description: A directory group, by the name the identity provider gives it, or * for everybody. + description: 'A directory group, by the name the identity provider gives it, or * for everybody. A team is written team: followed by the team''s id, as in team:Tm4Qx8LpV2nWc7RbY1sKd0Ze.' schema: type: string minLength: 1 @@ -19326,6 +20299,12 @@ components: systemOwned: type: boolean description: Whether it comes with OpenBot rather than belonging to a person. + packageBotId: + type: + - string + - 'null' + readOnly: true + description: 'Which of the Bots an OpenBot starts with this one is, so a client recognises it in whichever organization it is in. It is the id that Bot has in the install package: the same as id in the organization `default`, and the package''s id on another organization''s copy, whose own id is generated. Null for a Bot somebody made. Never accepted when a Bot is created or changed.' endpoint: type: - string @@ -19352,6 +20331,9 @@ components: mine: type: boolean description: Whether the caller created it. Separate from canManage, which is also true for an administrator on everybody's Bots. + withheld: + type: boolean + description: 'Whether it is somebody else''s private Bot, listed for an admin''s screens (listBots with scope=organization) and nothing more. Such a Bot carries its id, name, avatar and the caller''s own state with it only: title and roleDescription are empty, endpoint is null, instructions and framework are absent, hasAuth, hasCallbackToken, isolated, builtIn, runsOnOpenBotModel, keyFromOpenBot and canManage are false. Absent or false on every other Bot.' assignedToMe: type: boolean description: Whether an administrator assigned this Bot to the caller. @@ -20603,7 +21585,7 @@ components: readOnly: true ssoRequired: type: boolean - description: Whether people must sign in through the organization's identity provider. The administrators the deployment's configuration names keep social sign-in as their way in. + description: Whether people must sign in through the company's identity provider. It applies to signing in to the whole OpenBot, so it is set only in the organization `default`. The administrators the deployment's configuration names keep social sign-in as their way in. actionRecording: type: boolean description: Whether what Bots do on their computers is recorded, to read in computer actions. @@ -20688,7 +21670,7 @@ components: description: The model OpenBot's own Bots run on, when one is set. directoryGroups: type: array - description: The directory groups people belong to, by name. + description: The directory groups the organization's members belong to, by name. items: type: string apps: @@ -20840,7 +21822,12 @@ components: type: boolean groups: type: object - description: What each directory group is set to, by the group's name. A group absent sets nothing. Team scopes will be added when teams arrive. + description: What each directory group is set to, by the group's name. A group absent sets nothing. + additionalProperties: + type: boolean + teams: + type: object + description: What each team is set to, by the team's id. A team absent sets nothing. A team's switch can only turn a permission on for the people in it, and in the teams beneath it. additionalProperties: type: boolean CapabilityPage: @@ -20887,7 +21874,18 @@ components: type: object minProperties: 1 maxProperties: 100 - description: By directory group name, 1 to 200 characters. Team scopes will be added when teams arrive. + description: By directory group name, 1 to 200 characters. + propertyNames: + minLength: 1 + maxLength: 200 + pattern: ^[^\x00]*\S[^\x00]*$ + additionalProperties: + $ref: '#/components/schemas/SwitchValue' + teams: + type: object + minProperties: 1 + maxProperties: 100 + description: By team id. A team that is not one of this organization's is not found. propertyNames: minLength: 1 maxLength: 200 @@ -20908,12 +21906,13 @@ components: - organization - role - group - description: 'Whose switch: the organization''s, a member role''s, or a directory group''s. Team scopes will be added when teams arrive.' + - team + description: 'Whose switch: the organization''s, a member role''s, a team''s, or a directory group''s.' scopeId: type: string maxLength: 200 pattern: ^[^\x00]*$ - description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive. + description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group. capability: $ref: '#/components/schemas/CapabilityId' allowed: @@ -20961,12 +21960,13 @@ components: - organization - role - group - description: 'Whose switch: the organization''s, a member role''s, or a directory group''s. Team scopes will be added when teams arrive.' + - team + description: 'Whose switch: the organization''s, a member role''s, a team''s, or a directory group''s.' scopeId: type: string maxLength: 200 pattern: ^[^\x00]*$ - description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive. + description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group. capability: type: string maxLength: 100 @@ -21065,10 +22065,11 @@ components: - organization - role - group - description: 'Whose switch: the organization''s, a member role''s, or a directory group''s. Team scopes will be added when teams arrive.' + - team + description: 'Whose switch: the organization''s, a member role''s, a team''s, or a directory group''s.' scopeId: type: string - description: Empty for the organization; admin or member for a role; a directory group's name for a group. + description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group. capability: type: string allowed: @@ -21089,9 +22090,10 @@ components: - organization - role - group + - team scopeId: type: string - description: The role or group that decided it. Empty otherwise. + description: The role, the group's name or the team's id that decided it. Empty otherwise. CapabilityPreview: type: object required: @@ -21277,16 +22279,17 @@ components: properties: id: type: string - description: organization, or group: for a directory group. Team scopes will be added when teams arrive. + description: organization, team: for a team, or group: for a directory group. scopeKind: type: string enum: - organization - group - description: 'Whose policy: the organization''s, or a directory group''s. Team scopes will be added when teams arrive.' + - team + description: 'Whose policy: the organization''s, a team''s, or a directory group''s.' scopeId: type: string - description: The directory group's name. Empty for the organization. + description: The team's id, or the directory group's name. Empty for the organization. mode: $ref: '#/components/schemas/NetworkMode' rules: @@ -21353,12 +22356,13 @@ components: enum: - organization - group - description: 'Whose policy: the organization''s, or a directory group''s. Team scopes will be added when teams arrive.' + - team + description: 'Whose policy: the organization''s, a team''s, or a directory group''s.' scopeId: type: string maxLength: 200 pattern: ^[^\x00]*$ - description: The directory group's name. Empty for the organization. + description: The team's id, or the directory group's name. Empty for the organization. mode: $ref: '#/components/schemas/NetworkMode' rules: @@ -21771,11 +22775,11 @@ components: clientUrl: type: string minLength: 1 - description: The socket's address, without the /websocket it ends in or its query. A ws or wss address, or a path on this server. + description: The socket's address, without the /websocket it ends in or its query. A ws or wss address, or a path on this server, which is resolved against the address the API was called at. Where it is on this server, the socket is opened with the credential that made the token (see createConversationJoinToken). topic: type: string pattern: ^thread:.+$ - description: The topic to join on the socket, thread:{threadId}. + description: 'The topic to join on the socket, as the realtime gateway knows the thread. Use it as given: outside the organization default it does not name threadId, so a topic made from threadId joins nothing.' CredentialKind: type: string description: 'What a credential is for. model: a key OpenBot''s Bots call a model with. connector: an app''s key. mcp: a token for an app''s server. agent: a key for a company''s own agent. mcp_oauth_client: the organization''s registration with an app. mcp_user_token: one person''s sign-in to an app, kept when they connected it.' @@ -21788,7 +22792,7 @@ components: - mcp_user_token Credential: type: object - description: 'A credential in the vault as the API shows it: what it is for and whether it is live. Never its secret, which only ever goes in.' + description: 'A credential in the organization''s vault as the API shows it: what it is for and whether it is live. Never its secret, which only ever goes in.' required: - id - kind @@ -22014,7 +23018,7 @@ components: SharedAccountApproval: type: object additionalProperties: false - description: 'Who may have a Bot use an app''s one shared account, approved by an administrator: only the Bot''s owner, named people and directory groups, or everybody; and whether the Bot may act on what people outside the organization send it.' + description: 'Who may have a Bot use an app''s one shared account, approved by an administrator: only the Bot''s owner, named people, teams and directory groups, or everyone in the organization (team); and whether the Bot may act on what people outside the organization send it. A member of kind team names one of the organization''s teams by id; a team of another organization is not found.' required: - audience - outsideInput @@ -22043,6 +23047,7 @@ components: enum: - user - group + - team value: type: string minLength: 1 @@ -22563,7 +23568,7 @@ components: properties: id: type: string - description: The caller's own id for the message, so a retry is the same message. + description: The caller's own id for the message, any string, so a retry in the same conversation is the same message. The conversation's messages list it under this id. minLength: 1 maxLength: 160 text: @@ -22815,6 +23820,9 @@ components: threadId: type: string description: The new thread's id. + liveThreadId: + type: string + description: The id that live updates about this thread carry. Compare an incoming update with this one, and use threadId everywhere else. It is threadId itself in the organization default. Left out by a server that names threads one way only, where it is threadId. ConversationThreadStatus: type: object required: @@ -22826,6 +23834,9 @@ components: known: type: boolean description: Whether the thread still holds the caller's conversation. + liveThreadId: + type: string + description: The id that live updates about this thread carry. Compare an incoming update with this one, and use threadId everywhere else. It is threadId itself in the organization default. Left out by a server that names threads one way only, where it is threadId. TaskStatus: type: string enum: @@ -23040,7 +24051,7 @@ components: enum: - personal - shared - description: Each person's own account, or one account OpenBot holds for everybody. + description: Each person's own account, or one account OpenBot holds for everybody in the organization. AppOwnerGrants: type: string enum: @@ -23102,7 +24113,7 @@ components: type: string App: type: object - description: 'An app this OpenBot has added for its Bots, with the actions it offers. No secret is ever part of an app: hasCredential says whether a key or client is kept for it.' + description: 'An app the organization has added for its Bots, with the actions it offers. No secret is ever part of an app: hasCredential says whether a key or client is kept for it.' required: - id - title @@ -23187,7 +24198,7 @@ components: oneOf: - $ref: '#/components/schemas/AppAccountMode' - type: 'null' - description: 'Whose account an app from the directory acts in: each person''s own, or one account OpenBot holds for everybody. Null for an app with no account at all, and for any other app.' + description: 'Whose account an app from the directory acts in: each person''s own, or one account OpenBot holds for everybody in the organization. Null for an app with no account at all, and for any other app.' sharedAccountConnected: type: boolean description: Whether a shared app's one account is connected. False for any other app. @@ -23420,7 +24431,7 @@ components: enum: - person - deployment - description: 'Whose accounts they are: people''s own (person), or the one OpenBot holds for everybody (deployment).' + description: 'Whose accounts they are: people''s own (person), or the one OpenBot holds for everybody in the organization (deployment).' count: type: integer minimum: 0 @@ -24864,6 +25875,32 @@ components: description: The actions given to the Bot, written /. items: type: string + AppTeamGrants: + type: object + description: The teams the app is granted to. + required: + - teams + properties: + teams: + type: array + description: Each team's id, in order. + items: + type: string + AppTeamGrantsInput: + type: object + additionalProperties: false + required: + - teams + properties: + teams: + type: array + maxItems: 100 + description: The id of each team of this organization to grant it to. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ GiveableApp: type: object description: An app a person could give Bots they own. @@ -25135,7 +26172,7 @@ components: type: string minLength: 1 pattern: \S - description: The tool name a Bot draws it by. Trimmed. + description: The tool name a Bot draws it by. Trimmed. It can't start with @. title: type: string minLength: 1 @@ -25328,6 +26365,7 @@ components: - tools - ownerId - botIds + - usableOnYourBots properties: slug: type: string @@ -25357,6 +26395,9 @@ components: description: The Bots that offer it, by id. items: type: string + usableOnYourBots: + type: boolean + description: 'Whether the caller may put it on a Bot they own: it is their own, or it is granted to a team they are in. A Bot''s Skills page offers these.' SkillPage: type: object required: @@ -25408,6 +26449,32 @@ components: type: boolean default: false description: 'Make a new skill the organization''s. Only an admin may. It applies when the skill is made: rewriting one keeps whose it is.' + SkillTeamGrants: + type: object + description: The teams the skill is granted to. + required: + - teams + properties: + teams: + type: array + description: Each team's id, in order. + items: + type: string + SkillTeamGrantsInput: + type: object + additionalProperties: false + required: + - teams + properties: + teams: + type: array + maxItems: 100 + description: The id of each team of this organization to grant it to. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ DevicePlatform: type: string enum: @@ -27346,7 +28413,11 @@ components: - name - role - active + - personal properties: + personal: + type: boolean + description: 'Whether this is the caller''s own organization: the one OpenBot made for them when they first signed in.' id: type: string description: The organization's id. Opaque. @@ -27360,7 +28431,7 @@ components: $ref: '#/components/schemas/PersonRole' active: type: boolean - description: Whether the caller's session is working in this one. Always false for a request with no session. + description: 'Whether the caller is working in this one: the organization their session works in, or for an app''s token the one its OpenBot-Organization header names, else the caller''s own. Always false for a request made with an API key.' OrganizationPage: type: object required: @@ -27375,7 +28446,7 @@ components: $ref: '#/components/schemas/Organization' canCreate: type: boolean - description: 'Whether the caller may create an organization: the server''s verdict, true for the deployment''s admins and for anybody signed in when the deployment lets them. The same on every page.' + description: 'Whether the caller may create another organization: the server''s verdict, true for anybody signed in where OpenBot keeps more than one organization. The same on every page.' nextCursor: type: - string @@ -27418,7 +28489,17 @@ components: - image - role - joinedAt + - removable + - assignableRoles properties: + removable: + type: boolean + description: 'Whether this membership can end: an admin can remove them and they can leave. The server''s verdict. False for the organization''s last owner, who stays in it, for the owner of their own organization, and for somebody this OpenBot''s settings keep as an admin of the organization.' + assignableRoles: + type: array + description: The roles the caller may give this member, their current one left out. The server's verdict. Empty when the caller may not change this member's role. + items: + $ref: '#/components/schemas/PersonRole' id: type: string description: The person's id. @@ -27459,7 +28540,104 @@ components: maxLength: 4096 pattern: ^[A-Za-z0-9_-]+$ description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. - AddOrganizationMemberRequest: + UpdateOrganizationRequest: + type: object + additionalProperties: false + required: + - name + properties: + name: + type: string + minLength: 1 + maxLength: 100 + pattern: ^[^\x00]*\S[^\x00]*$ + description: What people call it. + UpdateOrganizationMemberRequest: + type: object + additionalProperties: false + required: + - role + properties: + role: + $ref: '#/components/schemas/PersonRole' + OrganizationMemberResponse: + type: object + required: + - member + properties: + member: + $ref: '#/components/schemas/OrganizationMember' + InvitationSender: + type: object + description: Who sent an invitation. + required: + - name + - email + properties: + name: + type: + - string + - 'null' + description: What OpenBot calls them. Null until they choose. + email: + type: string + description: Their address. + OrganizationInvitation: + type: object + description: An invitation an organization sent, as its admins see it. status is the server's verdict. + required: + - id + - email + - role + - status + - invitedBy + - createdAt + - expiresAt + properties: + id: + type: string + description: The invitation's id. Opaque. + email: + type: string + description: The address it was sent to. + role: + $ref: '#/components/schemas/AssignableRole' + status: + type: string + enum: + - pending + - expired + - declined + description: pending while it waits for an answer, expired once its seven days ran out, declined when the person turned it down. + invitedBy: + $ref: '#/components/schemas/InvitationSender' + createdAt: + type: string + format: date-time + description: When it was sent. + expiresAt: + type: string + format: date-time + description: When it stops being accepted. + OrganizationInvitationPage: + type: object + required: + - invitations + - nextCursor + properties: + invitations: + type: array + description: The newest first. + items: + $ref: '#/components/schemas/OrganizationInvitation' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + CreateOrganizationInvitationRequest: type: object additionalProperties: false required: @@ -27471,16 +28649,317 @@ components: minLength: 3 maxLength: 320 pattern: ^[^\s\x00]+@[^\s\x00]+$ - description: The address of somebody who already has an account here. + description: The address of the person to invite. role: $ref: '#/components/schemas/AssignableRole' - OrganizationMemberResponse: + OrganizationInvitationResponse: + type: object + required: + - invitation + - delivery + properties: + invitation: + $ref: '#/components/schemas/OrganizationInvitation' + delivery: + type: string + enum: + - emailed + - link + description: How the person hears of it. emailed when OpenBot sent them an email. link when it could not or is not set up to, so the inviter passes the invitation's link on themselves. Either way the person sees the invitation in OpenBot when they sign in. + Invitation: + type: object + description: An invitation as the person it was sent to sees it. status is the server's verdict. + required: + - id + - organization + - role + - status + - invitedBy + - createdAt + - expiresAt + properties: + id: + type: string + description: The invitation's id. Opaque. + organization: + type: object + description: The organization it is an invitation to. + required: + - id + - slug + - name + properties: + id: + type: string + description: The organization's id. Opaque. + slug: + type: string + description: Its short name. + name: + type: string + description: What people call it. + role: + $ref: '#/components/schemas/AssignableRole' + status: + type: string + enum: + - pending + - expired + - accepted + - declined + - canceled + description: pending while it can still be answered. expired once its seven days ran out, accepted or declined once the person answered, canceled when the organization took it back. + invitedBy: + $ref: '#/components/schemas/InvitationSender' + createdAt: + type: string + format: date-time + description: When it was sent. + expiresAt: + type: string + format: date-time + description: When it stops being accepted. + InvitationPage: + type: object + required: + - invitations + - nextCursor + properties: + invitations: + type: array + description: The newest first. + items: + $ref: '#/components/schemas/Invitation' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + InvitationResponse: + type: object + required: + - invitation + properties: + invitation: + $ref: '#/components/schemas/Invitation' + TeamSource: + type: string + description: 'Where a team comes from. openbot is a team made here. directory is a group of the company''s directory, kept in step with it: its name and its people are the directory''s and can''t be changed here.' + enum: + - openbot + - directory + TeamRole: + type: string + description: A person's role in a team. A maintainer can rename the team and add and remove its people; a member cannot. + enum: + - maintainer + - member + Team: + type: object + description: One team of an organization, as one of the organization's members sees it. role and canManage are the server's verdicts about the caller. + required: + - id + - name + - description + - parentTeamId + - source + - memberCount + - role + - canManage + - canMove + - canDelete + - createdAt + properties: + id: + type: string + description: The team's id. Opaque. + name: + type: string + description: What people call it. Unique in its organization. + description: + type: + - string + - 'null' + description: What the team is for, when somebody has said. + parentTeamId: + type: + - string + - 'null' + description: The team this one sits under, whose grants its members also have. Null for a team under none. + source: + $ref: '#/components/schemas/TeamSource' + memberCount: + type: integer + minimum: 0 + description: How many people are in the team itself. + role: + oneOf: + - $ref: '#/components/schemas/TeamRole' + - type: 'null' + description: The caller's role in the team. Null when they are not in it. + canManage: + type: boolean + description: 'Whether the caller may rename the team and add and remove its people: the server''s verdict.' + canMove: + type: boolean + description: 'Whether the caller may put the team under another team or take it out from under one: the server''s verdict, true for an owner or an admin of the organization.' + canDelete: + type: boolean + description: 'Whether the caller may delete the team: the server''s verdict, true for an owner or an admin of the organization, and never for a team that comes from the company''s directory.' + createdAt: + type: string + format: date-time + description: When the team was created. + TeamPage: + type: object + required: + - teams + - canCreate + - nextCursor + properties: + teams: + type: array + description: In the order they were created. + items: + $ref: '#/components/schemas/Team' + canCreate: + type: boolean + description: 'Whether the caller may create a team here: the server''s verdict. The same on every page.' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + CreateTeamRequest: + type: object + additionalProperties: false + required: + - name + properties: + name: + type: string + minLength: 1 + maxLength: 100 + pattern: ^[^\x00]*\S[^\x00]*$ + description: What people call it. + description: + type: string + maxLength: 500 + pattern: ^[^\x00]*$ + description: What the team is for. + parentTeamId: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + description: A team of the same organization to put this one under. + TeamResponse: + type: object + required: + - team + properties: + team: + $ref: '#/components/schemas/Team' + UpdateTeamRequest: + type: object + additionalProperties: false + minProperties: 1 + properties: + name: + type: string + minLength: 1 + maxLength: 100 + pattern: ^[^\x00]*\S[^\x00]*$ + description: What people call it. + description: + type: + - string + - 'null' + maxLength: 500 + pattern: ^[^\x00]*$ + description: What the team is for. Null clears it. + parentTeamId: + type: + - string + - 'null' + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + description: A team of the same organization to put this one under. Null takes it out from under its parent. + TeamMember: + type: object + description: One person in a team. + required: + - id + - email + - name + - image + - role + - isCaller + - joinedAt + properties: + id: + type: string + description: The person's id. + email: + type: string + description: Their address. + name: + type: + - string + - 'null' + description: What OpenBot calls them. Null until they choose. + image: + type: + - string + - 'null' + description: Their picture's address, when they have one. + role: + $ref: '#/components/schemas/TeamRole' + isCaller: + type: boolean + description: Whether this person is the caller. + joinedAt: + type: string + format: date-time + description: When they joined the team. + TeamMemberPage: + type: object + required: + - members + - nextCursor + properties: + members: + type: array + description: In the order they joined the team. + items: + $ref: '#/components/schemas/TeamMember' + nextCursor: + type: + - string + - 'null' + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: Pass as cursor for the next page. Null ends the list. Written in URL-safe base64, the only form the cursor parameter accepts. + PutTeamMemberRequest: + type: object + additionalProperties: false + required: + - role + properties: + role: + $ref: '#/components/schemas/TeamRole' + TeamMemberResponse: type: object required: - member properties: member: - $ref: '#/components/schemas/OrganizationMember' + $ref: '#/components/schemas/TeamMember' ApprovalStatus: type: string description: Where an approval stands. pending waits for the person. approved and denied are decided, and consumed is started; the server then carries the conversation on. completed is finished. @@ -29174,6 +30653,19 @@ components: description: The directory groups, by name. items: type: string + teams: + type: array + description: The organization's teams. An action names one in group, as team:. + items: + type: object + required: + - id + - name + properties: + id: + type: string + name: + type: string apps: type: array items: @@ -29231,7 +30723,7 @@ components: WhatIfAction: type: object additionalProperties: false - description: 'One action a Bot might take. Who: a Bot, and either the person whose accounts it runs on or a directory group, for any member of it. What starts the run. Then either an app''s tool, or something on the Bot''s computer. A field that does not apply is empty.' + description: 'One action a Bot might take. Who: a Bot, and either the person whose accounts it runs on or a team or directory group, for any member of it. What starts the run. Then either an app''s tool, or something on the Bot''s computer. A field that does not apply is empty.' required: - bot - person @@ -29254,7 +30746,7 @@ components: description: The person's id. Empty when a group is named. group: type: string - description: A directory group's name. Empty when a person is named. + description: A directory group's name, or team: for one of the organization's teams. Empty when a person is named. initiator: $ref: '#/components/schemas/WhatIfInitiator' surface: @@ -29532,10 +31024,10 @@ components: - owner - people - team - description: 'Who may steer a Bot that uses a shared app''s account: only the Bot''s owner, the people and directory groups named, or everybody in the organization.' + description: 'Who may steer a Bot that uses a shared app''s account: only the Bot''s owner, the people, teams and directory groups named, or everyone in the organization (team).' SharedUseMember: type: object - description: One person or directory group an audience names. + description: One person, team or directory group an audience names. required: - kind - value @@ -29545,9 +31037,10 @@ components: enum: - user - group + - team value: type: string - description: The person's id, or the directory group's name. + description: The person's id, the team's id, or the directory group's name. SharedUseApproval: type: object description: 'An audience for a Bot''s use of a shared app''s account: who may steer the Bot there, and whether a run started by outside input (an email, a webhook) may use the account too.' @@ -29563,7 +31056,7 @@ components: description: Whether runs started by outside input are covered. members: type: array - description: The people and groups named, when the audience is people. Empty otherwise. + description: The people, teams and groups named, when the audience is people. Empty otherwise. items: $ref: '#/components/schemas/SharedUseMember' SharedUseRequest: @@ -30249,10 +31742,10 @@ components: enum: - team - people - description: team is everybody in the organization; people is the people and groups named. + description: team is everyone in the organization; people is the people, teams and groups named. TeamBot: type: object - description: A Bot published to the team, as the caller sees it. Who it reaches (people, groups and assignedGroups) is present only for its owner and administrators. + description: A published Bot, as the caller sees it. Who it reaches (people, teams, groups and assignedGroups) is present only for its owner and administrators. required: - botId - name @@ -30285,7 +31778,7 @@ components: description: Whether an administrator put it in the caller's Bots list, where they can't hide it. visibleToTeam: type: boolean - description: False while its name or description would leave teammates unable to tell it apart, so they can't see it. + description: False while its name or description would leave the people it is published to unable to tell it apart, so they can't see it. people: type: array description: The people it is published to, by email. @@ -30296,6 +31789,11 @@ components: description: The directory groups it is published to. items: type: string + teams: + type: array + description: The teams it is published to, by each team's id. + items: + type: string assignedGroups: type: array description: The directory groups an administrator assigned it to; * is everybody. @@ -30347,6 +31845,15 @@ components: items: type: string maxLength: 200 + teams: + type: array + maxItems: 100 + description: With people, the teams to publish to, by each team's id. Every one must be a team of this organization. The people in a team, and in the teams under it, can use the Bot, and nobody else in the organization can. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ PublishedTeamBot: type: object required: @@ -30379,7 +31886,7 @@ components: description: 'allow_once: this time. allow_always: always, for this Team Bot. allow_all_team_bots: always, for every Team Bot. skip: not now, taking back an earlier answer for this Team Bot.' Computer: type: object - description: 'One computer as an administrator sees it: a person''s, or an isolated Bot''s. Where every person''s Bots share one computer, one person''s seat on one Bot there.' + description: 'One of the organization''s computers as its administrator sees it: a person''s, or an isolated Bot''s. Where every person''s Bots share one computer, one person''s seat on one Bot there.' required: - id - computer @@ -32354,6 +33861,11 @@ components: oneOf: - $ref: '#/components/schemas/LearningAutomatic' - type: 'null' + organizationSpaceId: + description: 'The space OpenBot keeps for this organization alone, which its Bots learn into unless an administrator chooses another. Another space of the organization''s is named after it: this id, a hyphen, then a name of the administrator''s choosing. The id says nothing a person can read, so a screen names the space by the organization and never shows it. Null, or absent, where OpenBot keeps no space for the organization alone and its default is whichever space is assigned or chosen.' + oneOf: + - $ref: '#/components/schemas/LearningSpaceId' + - type: 'null' UpdateLearningSettingsRequest: type: object additionalProperties: false @@ -32738,7 +34250,7 @@ components: - closed - open - choose - description: 'Who else''s Bots use the skills learned in a person''s own space. closed: only their own Bots. open: every Bot. choose: every Bot, for the skills they open one by one.' + description: 'Who else''s Bots use the skills learned in a person''s own space. closed: only their own Bots. open: every Bot in the organization. choose: every Bot in the organization, for the skills they open one by one. Never a Bot in another organization.' PersonalLearnedSkill: type: object required: @@ -34096,12 +35608,23 @@ components: requestId: req_example traceId: trace_example SettingsConflict: - description: Single sign-on can't be required before an identity provider is registered, or the Idempotency-Key was used for a different request. + description: Single sign-on can't be required before an identity provider is registered, ssoRequired was sent in an organization other than `default`, or the Idempotency-Key was used for a different request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: + notTheFirstOrganization: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: Requiring SSO applies to signing in to this OpenBot as a whole, so it can't be set for one organization. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example noProvider: value: type: https://open.bot/errors/conflict @@ -35419,6 +36942,35 @@ components: retryable: false requestId: req_example traceId: trace_example + AppOrTeamNotFound: + description: OpenBot has no app by that id, a team named is not one of this organization's, or the organization does not exist. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + app: + value: + type: https://open.bot/errors/app-not-found + title: App not found. + status: 404 + detail: OpenBot has no app called asana. + code: APP_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example TooManyPendingRequests: description: The person already has as many requests waiting as they may. content: @@ -35485,12 +37037,23 @@ components: requestId: req_example traceId: trace_example InvalidComponent: - description: 'A field is missing or blank once trimmed, holds text that can''t be kept, or doesn''t fit this kind of component: a title or source for one that comes with OpenBot, a Playground name that isn''t custom_ and lower-case letters, numbers and underscores, or a data function this OpenBot doesn''t ship.' + description: 'A field is missing or blank once trimmed, holds text that can''t be kept, or doesn''t fit this kind of component: a title or source for one that comes with OpenBot, a Playground name that isn''t custom_ and lower-case letters, numbers and underscores, an announced name that starts with @, or a data function this OpenBot doesn''t ship.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: + nameStartsWithAt: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: Component at index 0 has a name that starts with @, which a component's name can't. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example announcement: value: type: https://open.bot/errors/validation-error @@ -35608,7 +37171,7 @@ components: requestId: req_example traceId: trace_example SkillNotFound: - description: No skill has that slug, it is somebody else's and the caller isn't an admin, or the organization does not exist. + description: No skill has that slug, the caller isn't an admin and can't see it, or the organization does not exist. content: application/problem+json: schema: @@ -35683,6 +37246,35 @@ components: retryable: false requestId: req_example traceId: trace_example + SkillOrTeamNotFound: + description: There is no skill by that slug, a team named is not one of this organization's, or the organization does not exist. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + skill: + value: + type: https://open.bot/errors/skill-not-found + title: Skill not found. + status: 404 + detail: There is no skill called standup. + code: SKILL_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example TransportUnavailable: description: 'This deployment hasn''t set up that way of reaching people: push notifications, the Slack and Teams pairing, or text messages. Or the organization does not exist.' content: @@ -35749,12 +37341,23 @@ components: requestId: req_example traceId: trace_example InvalidDestination: - description: The request doesn't match the API, the conversation isn't the person's or the Bot isn't in it, a phone's verification expired, was used already or its code was wrong, or the phone is connected to another person. + description: The request doesn't match the API, the conversation isn't the person's or the Bot isn't in it, a phone's verification expired, was used already or its code was wrong, the phone is connected to another person, or the Slack account, Teams account or phone is connected in another organization. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: + connectedInAnotherOrganization: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: That account is already connected to OpenBot in another organization. Disconnect it there, then connect it here. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example notTheirs: value: type: https://open.bot/errors/validation-error @@ -36106,7 +37709,25 @@ components: retryable: true requestId: req_example traceId: trace_example - InvalidOrganizationMember: + OwnerStays: + description: 'The person stays in the organization: they own it, or this OpenBot''s settings keep them as an admin of it. The members list says who, as removable.' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + owner: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: They own this organization, so they stay a member of it. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + InvalidOrganizationInvitation: description: The address or the role is missing or malformed, or the Idempotency-Key is. content: application/problem+json: @@ -36124,8 +37745,48 @@ components: retryable: false requestId: req_example traceId: trace_example - OrganizationOrPersonNotFound: - description: The organization does not exist or is not visible to the caller, or nobody here has that address. + OrganizationInvitationConflict: + description: They are already a member, or already have an invitation waiting. Or the Idempotency-Key was used for a different request. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + already: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: They're already a member of this organization. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + invited: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: They already have an invitation waiting. Cancel it to send a new one. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + reused: + value: + type: https://open.bot/errors/idempotency-key-conflict + title: That Idempotency-Key was used for a different request. + status: 409 + detail: That Idempotency-Key was used for a different request. + code: IDEMPOTENCY_KEY_CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + OrganizationOrInvitationNotFound: + description: The organization does not exist or is not visible to the caller, or it has no such invitation. content: application/problem+json: schema: @@ -36142,30 +37803,48 @@ components: retryable: false requestId: req_example traceId: trace_example - person: + invitation: value: - type: https://open.bot/errors/person-not-found - title: Person not found. + type: https://open.bot/errors/invitation-not-found + title: Invitation not found. status: 404 - detail: Nobody here has that address. They need to sign in to OpenBot once first. - code: PERSON_NOT_FOUND + detail: Couldn't find that invitation. + code: INVITATION_NOT_FOUND category: not_found retryable: false requestId: req_example traceId: trace_example - OrganizationMemberConflict: - description: They are already a member. Or the Idempotency-Key was used for a different request. + InvitationNotFound: + description: There is no such invitation, or it was sent to another address. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: - already: + invitation: + value: + type: https://open.bot/errors/invitation-not-found + title: Invitation not found. + status: 404 + detail: Couldn't find that invitation. Check that you're signed in with the address it was sent to. + code: INVITATION_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + InvitationNotWaiting: + description: The invitation expired, was canceled or was already answered. Or the Idempotency-Key was used for a different request. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + expired: value: type: https://open.bot/errors/conflict title: The request conflicts with the current state. status: 409 - detail: They're already a member of this organization. + detail: This invitation has expired. Ask whoever invited you to send a new one. code: CONFLICT category: conflict retryable: false @@ -36182,6 +37861,169 @@ components: retryable: false requestId: req_example traceId: trace_example + InvalidTeam: + description: The name, the description or the parent is missing or malformed, the parent is not a team that can hold this one, or the Idempotency-Key is malformed. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + name: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A name of 1 to 100 characters is required. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + parent: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A team can't sit under itself or under a team beneath it. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + TeamConflict: + description: Another team of the organization has that name. Or the Idempotency-Key was used for a different request. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + nameTaken: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: Another team here already has that name. Choose another. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + reused: + value: + type: https://open.bot/errors/idempotency-key-conflict + title: That Idempotency-Key was used for a different request. + status: 409 + detail: That Idempotency-Key was used for a different request. + code: IDEMPOTENCY_KEY_CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + TeamNotFound: + description: The organization or the team does not exist or is not visible to the caller. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + organization: + value: + type: https://open.bot/errors/organization-not-found + title: Organization not found. + status: 404 + detail: Couldn't find that organization. + code: ORGANIZATION_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + TeamForbidden: + description: 'The caller may not change this team: they are neither an owner or an admin of the organization nor one of the team''s maintainers. Or the team comes from the company''s directory, which is where it is changed.' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + notAllowed: + value: + type: https://open.bot/errors/permission-denied + title: Permission denied. + status: 403 + detail: Only an admin of this organization or a maintainer of this team can change it. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + directory: + value: + type: https://open.bot/errors/permission-denied + title: Permission denied. + status: 403 + detail: This team comes from your company's directory. Change its people there. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + InvalidTeamMember: + description: The role is missing or malformed, or the Idempotency-Key is. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + role: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A role of maintainer or member is required. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + TeamOrPersonNotFound: + description: The organization or the team does not exist or is not visible to the caller, or the person is not a member of the organization. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + person: + value: + type: https://open.bot/errors/person-not-found + title: Person not found. + status: 404 + detail: They aren't a member of this organization. Add them to the organization first. + code: PERSON_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example ApprovalsOwnOnly: description: 'The caller asked about somebody else''s approvals, questions, preferences or rules, which only that person may read or change: an administrator can''t either.' content: @@ -36814,6 +38656,35 @@ components: retryable: true requestId: req_example traceId: trace_example + OrganizationComputerNotFound: + description: The computer named is not one of the organization's Bots' computers, or the organization does not exist. + content: + application/problem+json: + schema: + $ref: '#/components/schemas/Problem' + examples: + computer: + value: + type: https://open.bot/errors/bot-not-found + title: Bot not found. + status: 404 + detail: Couldn't find that computer. + code: BOT_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + organization: + value: + type: https://open.bot/errors/organization-not-found + title: Organization not found. + status: 404 + detail: Couldn't find that organization. + code: ORGANIZATION_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example ComputerBotNotFound: description: The Bot does not exist or is not the caller's to use, a file or a control request the call names does not exist, or the organization does not. content: @@ -39081,11 +40952,13 @@ components: summary: A new thread id. value: threadId: 6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a + liveThreadId: 2b503bf7-514a-8c4e-b132-3ca9b729ffeb ConversationThreadStatusExample: summary: A thread that is still there. value: threadId: 6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a known: true + liveThreadId: 2b503bf7-514a-8c4e-b132-3ca9b729ffeb TaskPageExample: summary: One task, ready to read. value: @@ -39697,6 +41570,11 @@ components: granted: - notion/notion-fetch - notion/notion-search + AppTeamGrantsExample: + summary: Granted to one team. + value: + teams: + - Tm4Qx8LpV2nWc7RbY1sKd0Ze GiveableAppPageExample: summary: Two apps the person could give their Bots. value: @@ -39976,6 +41854,7 @@ components: ownerId: user_3f1c9a botIds: - general-assistant + usableOnYourBots: true - slug: weekly-report title: Weekly report summary: Sum up the week's work for the team. @@ -39985,6 +41864,7 @@ components: botIds: - general-assistant - research-assistant + usableOnYourBots: false nextCursor: null SkillExample: summary: A person's own skill, offered by one Bot. @@ -39998,6 +41878,12 @@ components: ownerId: user_3f1c9a botIds: - general-assistant + usableOnYourBots: true + SkillTeamGrantsExample: + summary: Granted to one team. + value: + teams: + - Tm4Qx8LpV2nWc7RbY1sKd0Ze DevicePageLast: summary: A person's iPhone, on one page. value: @@ -40455,19 +42341,21 @@ components: value: cancelled: true OrganizationPageLast: - summary: Somebody in two organizations, working in the first. + summary: Somebody in their own organization and one they created, working in their own. value: organizations: - - id: default - slug: default - name: Acme - role: admin + - id: Wm4pZ7tKc1Xb9RnQ2sYd6hLe + slug: dana + name: Dana's organization + role: owner active: true + personal: true - id: Jq3xT9mLw2Vb8RnC5sYd0fKe slug: acme-research name: Acme Research role: owner active: false + personal: false canCreate: true nextCursor: null CreatedOrganization: @@ -40479,6 +42367,7 @@ components: name: Acme Research role: owner active: false + personal: false OrganizationMemberPageLast: summary: An organization's members, on one page. value: @@ -40489,23 +42378,196 @@ components: image: null role: owner joinedAt: '2026-11-14T09:12:40.000Z' + removable: false + assignableRoles: [] - id: 2fn8w1c6y4tq7h0mbe3s email: sam.ortiz@acme.com name: Sam Ortiz image: null role: member joinedAt: '2026-11-14T09:20:05.000Z' + removable: true + assignableRoles: + - owner + - admin nextCursor: null - AddedOrganizationMember: - summary: Somebody added as a member. + RenamedOrganization: + summary: An organization with its new name. + value: + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research Lab + role: owner + active: true + personal: false + PromotedOrganizationMember: + summary: A member an owner has made an owner too. value: member: id: 2fn8w1c6y4tq7h0mbe3s email: sam.ortiz@acme.com name: Sam Ortiz image: null - role: member + role: owner joinedAt: '2026-11-14T09:20:05.000Z' + removable: true + assignableRoles: + - admin + - member + OrganizationInvitationPageLast: + summary: One invitation waiting and one that expired. + value: + invitations: + - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + email: sam.ortiz@acme.com + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + - id: 0c2d7a53-1f4e-4f0a-8a57-3d1b2c9e7f42 + email: lee.park@acme.com + role: admin + status: expired + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-01T09:20:05.000Z' + expiresAt: '2026-11-08T09:20:05.000Z' + nextCursor: null + CreatedOrganizationInvitation: + summary: An invitation OpenBot could not email, so the inviter passes the link on. + value: + invitation: + id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + email: sam.ortiz@acme.com + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + delivery: link + InvitationPageLast: + summary: One invitation waiting for the caller. + value: + invitations: + - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + nextCursor: null + WaitingInvitation: + summary: An invitation the caller can still answer. + value: + invitation: + id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + JoinedOrganization: + summary: The organization somebody joined by accepting an invitation. + value: + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research + role: member + active: false + personal: false + TeamPageLast: + summary: An organization's teams, on one page. + value: + teams: + - id: Tm4Qx8LpV2nWc7RbY1sKd0Ze + name: Sales + description: Everybody who sells. + parentTeamId: null + source: openbot + memberCount: 2 + role: maintainer + canManage: true + canMove: true + canDelete: true + createdAt: '2026-11-15T09:12:40.000Z' + - id: Fn2Wc6Yt4Qh7M0be3sKq8xLp + name: Finance + description: null + parentTeamId: null + source: directory + memberCount: 1 + role: null + canManage: false + canMove: true + canDelete: false + createdAt: '2026-11-15T09:20:05.000Z' + canCreate: true + nextCursor: null + CreatedTeam: + summary: A team made in OpenBot. + value: + team: + id: Tm4Qx8LpV2nWc7RbY1sKd0Ze + name: Sales + description: Everybody who sells. + parentTeamId: null + source: openbot + memberCount: 0 + role: null + canManage: true + canMove: true + canDelete: true + createdAt: '2026-11-15T09:12:40.000Z' + TeamMemberPageLast: + summary: A team's people, on one page. + value: + members: + - id: 8kq2m4x7p1rvz3a9c5d0 + email: dana.whitfield@acme.com + name: Dana Whitfield + image: null + role: maintainer + isCaller: true + joinedAt: '2026-11-15T09:13:02.000Z' + - id: 2fn8w1c6y4tq7h0mbe3s + email: sam.ortiz@acme.com + name: Sam Ortiz + image: null + role: member + isCaller: false + joinedAt: '2026-11-15T09:20:05.000Z' + nextCursor: null + AddedTeamMember: + summary: Somebody put in a team. + value: + member: + id: 2fn8w1c6y4tq7h0mbe3s + email: sam.ortiz@acme.com + name: Sam Ortiz + image: null + role: member + isCaller: false + joinedAt: '2026-11-15T09:20:05.000Z' ApprovalPageExample: summary: One approval waiting, on the last page. value: @@ -41210,7 +43272,7 @@ components: assignedGroups: [] nextCursor: null TeamBotExample: - summary: Published to the whole team, seen by a teammate. + summary: Published to everyone in the organization, seen by one of them. value: teamBot: botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21 diff --git a/api/openapi/accounts.yaml b/api/openapi/accounts.yaml index e18d7cfbda..d06cf464cf 100644 --- a/api/openapi/accounts.yaml +++ b/api/openapi/accounts.yaml @@ -165,14 +165,22 @@ paths: operationId: revokePersonAccess summary: Remove a person's access description: >- - Stop a person from using OpenBot: their address can't sign in again, - and the sessions, API keys and app sign-ins they hold end at once. - They keep their record and their history, and restoring their access - lets them sign in again. Their connected credentials are retired too. - Only an administrator may do this, never to themselves, and never to - somebody the deployment's configuration names as an administrator. - Removing somebody already removed retires anything left and records - nothing new. + Remove a person from the organization. Where everybody has an + organization of their own (an OpenBot whose list of organizations + answers canCreate true), this ends their membership of this + organization alone: they lose its Bots and conversations from their + next request, and their account, sessions, API keys, their own + organization and any other they belong to are unchanged. Restoring + them puts the membership back with its role and teams. Where OpenBot + keeps one organization, it stops the person using OpenBot: their + address can't sign in again, and the sessions, API keys and app + sign-ins they hold end at once; restoring their access lets them sign + in again. Either way they keep their record and their history, and the + credentials they connected here are retired. Only an administrator may + do this, never to themselves, never to somebody the deployment's + configuration names as an administrator, and never to the + organization's owner. Removing somebody already removed retires + anything left and records nothing new. security: - webSession: [] - appOAuth: [people:write] @@ -215,10 +223,14 @@ paths: operationId: restorePersonAccess summary: Give a person their access back description: >- - Let a removed person sign in again. What ended when they were removed - stays ended: they sign in afresh and make new API keys. Only an - administrator may do this. Restoring somebody who was never removed - changes nothing and records nothing. + Give a removed person their access back. Where everybody has an + organization of their own, this puts back their membership of this + organization with the role and teams it had; their sessions and API + keys, which were never ended, work here again from their next request. + Where OpenBot keeps one organization, it lets them sign in again, and + what ended when they were removed stays ended: they sign in afresh and + make new API keys. Only an administrator may do this. Restoring + somebody who was never removed changes nothing and records nothing. security: - webSession: [] - appOAuth: [people:write] @@ -597,8 +609,8 @@ paths: operationId: createApiKey summary: Make an API key description: >- - Make an API key that acts as the person, inside this organization, - on the API only. The key itself is in this answer and never again: + Make an API key that acts as the person, in every organization they + are a member of, on the API. The key itself is in this answer and never again: OpenBot keeps only a hash of it. Only the person themselves may make one, signed in to OpenBot: a key can never make another key, and neither can an app's sign-in. A key ends when it expires, when it is diff --git a/api/openapi/admin-settings.yaml b/api/openapi/admin-settings.yaml index 4d939468d4..bff75128f2 100644 --- a/api/openapi/admin-settings.yaml +++ b/api/openapi/admin-settings.yaml @@ -14,7 +14,11 @@ paths: Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it - first. It names no identity provider and no version: only whether + first. Signed in, it is answered in an organization the caller is a + member of, and an organization they are not in, the organization + `default` included, answers exactly as one that does not exist. Nobody + signed in reads it in the organization `default`. It names no identity + provider and no version: only whether single sign-on is set up and required. x-openbot-singleton: true security: @@ -46,14 +50,16 @@ paths: operationId: getOrganizationSettings summary: Read the organization's settings description: >- - Return the settings an administrator sets for everybody: single - sign-on, recording computer actions, stopping idle computers, the - model and app allowlists, sharing learned skills, check-ins a day and - choosing a model. Beside them, read only, what an administrator needs - to set them: the model OpenBot runs on, the directory groups, the apps - an allowlist can name, the hosts every computer may reach, and whether - SCIM and OpenTelemetry are set up. Only an administrator may read - them. + Return the settings the organization's administrators set for its + members: single sign-on, recording computer actions, stopping idle + computers, the model and app allowlists, sharing learned skills, + check-ins a day and choosing a model. Each organization has its own, + and a new one starts with OpenBot's defaults. Beside them, read only, + what an administrator needs to set them: the model OpenBot runs on, + the directory groups of the organization's members, the apps an + allowlist can name, the hosts every computer may reach, and whether + SCIM and OpenTelemetry are set up. Only an administrator of the + organization may read them. x-openbot-singleton: true security: - webSession: [] @@ -91,7 +97,10 @@ paths: the audit trail with what it was before. Requiring single sign-on needs an identity provider registered first, and signs out everybody who signed in another way, apart from the administrators the deployment's - configuration names and the caller. Only an administrator may change + configuration names and the caller. Requiring single sign-on applies + to signing in to the whole OpenBot, so it is set only in the + organization `default`: sending ssoRequired in any other organization + answers 409. Only an administrator of the organization may change them. security: - webSession: [] @@ -467,8 +476,8 @@ paths: description: >- Return each permission switch as it applies to one person, so the apps hide what they may not use. The caller reads their own, as me; an - administrator reads anybody's. enforced is false where the deployment - keeps no switches and every default applies. + administrator of the organization reads any member's. enforced is + false where this OpenBot keeps no switches and every default applies. x-openbot-singleton: true security: - webSession: [] @@ -508,9 +517,12 @@ paths: operationId: stopPersonComputers summary: Stop a person's computers description: >- - Stop every Bot computer running for one person now, and record it on - the audit trail. Their Bots start a computer again when they next need - one. Only an administrator may do this. + Stop the computers of the organization's Bots that one person owns, + now, and record it on the audit trail. Their Bots start a computer + again when they next need one. A person's own computer is stopped + only from the organization `default`. A person who is not a member of + the organization is not found (PERSON_NOT_FOUND). Only an + administrator of the organization may do this. security: - webSession: [] - appOAuth: [people:write] @@ -803,9 +815,9 @@ paths: operationId: getModelUsage summary: Read which models Bots ran on description: >- - Return which models Bots ran on over the last days, with how many runs, - refusals and people each had, and the newest 50 runs. Only an - administrator may read it. + Return which models the organization's Bots ran on over the last days, + with how many runs, refusals and people each had, and the newest 50 + runs. Only an administrator of the organization may read it. x-openbot-singleton: true security: - webSession: [] @@ -853,9 +865,10 @@ paths: operationId: listComputerActions summary: List recorded computer actions description: >- - Return one page of the actions recorded on Bot computers while - recording computer actions is on, newest first. Records are kept for - actionRecordRetentionDays. Only an administrator may read them. A + Return one page of the actions recorded on the organization's Bots' + computers while recording computer actions is on, newest first. + Records are kept for actionRecordRetentionDays. Only an administrator + of the organization may read them. A missing cursor starts at the newest and nextCursor null ends the list. security: - webSession: [] @@ -985,12 +998,14 @@ components: name: networkPolicyId in: path required: true - description: organization, or group: for a directory group's. + description: >- + organization, team: for a team's, or group: for a directory + group's. schema: type: string minLength: 1 maxLength: 206 - pattern: ^(organization|group:[^\x00]*\S[^\x00]*)$ + pattern: ^(organization|team:[^\x00]*\S[^\x00]*|group:[^\x00]*\S[^\x00]*)$ schemas: Deployment: type: object @@ -1086,9 +1101,11 @@ components: ssoRequired: type: boolean description: >- - Whether people must sign in through the organization's identity - provider. The administrators the deployment's configuration names - keep social sign-in as their way in. + Whether people must sign in through the company's identity + provider. It applies to signing in to the whole OpenBot, so it is + set only in the organization `default`. The administrators the + deployment's configuration names keep social sign-in as their way + in. actionRecording: type: boolean description: Whether what Bots do on their computers is recorded, to read in computer actions. @@ -1167,7 +1184,7 @@ components: description: The model OpenBot's own Bots run on, when one is set. directoryGroups: type: array - description: The directory groups people belong to, by name. + description: The directory groups the organization's members belong to, by name. items: type: string apps: @@ -1299,7 +1316,15 @@ components: type: object description: >- What each directory group is set to, by the group's name. A group - absent sets nothing. Team scopes will be added when teams arrive. + absent sets nothing. + additionalProperties: + type: boolean + teams: + type: object + description: >- + What each team is set to, by the team's id. A team absent sets + nothing. A team's switch can only turn a permission on for the + people in it, and in the teams beneath it. additionalProperties: type: boolean CapabilityPage: @@ -1343,7 +1368,20 @@ components: minProperties: 1 maxProperties: 100 description: >- - By directory group name, 1 to 200 characters. Team scopes will be added when teams arrive. + By directory group name, 1 to 200 characters. + propertyNames: + minLength: 1 + maxLength: 200 + pattern: ^[^\x00]*\S[^\x00]*$ + additionalProperties: + $ref: '#/components/schemas/SwitchValue' + teams: + type: object + minProperties: 1 + maxProperties: 100 + description: >- + By team id. A team that is not one of this organization's is not + found. propertyNames: minLength: 1 maxLength: 200 @@ -1357,15 +1395,15 @@ components: properties: scopeKind: type: string - enum: [organization, role, group] + enum: [organization, role, group, team] description: >- - Whose switch: the organization's, a member role's, or a directory - group's. Team scopes will be added when teams arrive. + Whose switch: the organization's, a member role's, a team's, or a + directory group's. scopeId: type: string maxLength: 200 pattern: ^[^\x00]*$ - description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive. + description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group. capability: $ref: '#/components/schemas/CapabilityId' allowed: @@ -1407,15 +1445,15 @@ components: properties: scopeKind: type: string - enum: [organization, role, group] + enum: [organization, role, group, team] description: >- - Whose switch: the organization's, a member role's, or a directory - group's. Team scopes will be added when teams arrive. + Whose switch: the organization's, a member role's, a team's, or a + directory group's. scopeId: type: string maxLength: 200 pattern: ^[^\x00]*$ - description: Empty for the organization; admin or member for a role; a directory group's name for a group. Team scopes will be added when teams arrive. + description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group. capability: type: string maxLength: 100 @@ -1494,13 +1532,13 @@ components: properties: scopeKind: type: string - enum: [organization, role, group] + enum: [organization, role, group, team] description: >- - Whose switch: the organization's, a member role's, or a directory - group's. Team scopes will be added when teams arrive. + Whose switch: the organization's, a member role's, a team's, or a + directory group's. scopeId: type: string - description: Empty for the organization; admin or member for a role; a directory group's name for a group. + description: Empty for the organization; admin or member for a role; a team's id for a team; a directory group's name for a group. capability: type: string allowed: @@ -1513,10 +1551,10 @@ components: type: boolean decidedBy: type: string - enum: [default, organization, role, group] + enum: [default, organization, role, group, team] scopeId: type: string - description: The role or group that decided it. Empty otherwise. + description: The role, the group's name or the team's id that decided it. Empty otherwise. CapabilityPreview: type: object required: [check, people, counts, activity, warning] @@ -1655,16 +1693,16 @@ components: id: type: string description: >- - organization, or group: for a directory group. Team scopes will be added when teams arrive. + organization, team: for a team, or group: for a directory group. scopeKind: type: string - enum: [organization, group] + enum: [organization, group, team] description: >- - Whose policy: the organization's, or a directory group's. - Team scopes will be added when teams arrive. + Whose policy: the organization's, a team's, or a directory + group's. scopeId: type: string - description: The directory group's name. Empty for the organization. + description: The team's id, or the directory group's name. Empty for the organization. mode: $ref: '#/components/schemas/NetworkMode' rules: @@ -1719,15 +1757,15 @@ components: properties: scopeKind: type: string - enum: [organization, group] + enum: [organization, group, team] description: >- - Whose policy: the organization's, or a directory group's. - Team scopes will be added when teams arrive. + Whose policy: the organization's, a team's, or a directory + group's. scopeId: type: string maxLength: 200 pattern: ^[^\x00]*$ - description: The directory group's name. Empty for the organization. + description: The team's id, or the directory group's name. Empty for the organization. mode: $ref: '#/components/schemas/NetworkMode' rules: @@ -1961,12 +1999,24 @@ components: SettingsConflict: description: >- Single sign-on can't be required before an identity provider is - registered, or the Idempotency-Key was used for a different request. + registered, ssoRequired was sent in an organization other than + `default`, or the Idempotency-Key was used for a different request. content: application/problem+json: schema: $ref: './common.yaml#/components/schemas/Problem' examples: + notTheFirstOrganization: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: Requiring SSO applies to signing in to this OpenBot as a whole, so it can't be set for one organization. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example noProvider: value: type: https://open.bot/errors/conflict diff --git a/api/openapi/approvals.yaml b/api/openapi/approvals.yaml index 5f56496239..c854baf0f7 100644 --- a/api/openapi/approvals.yaml +++ b/api/openapi/approvals.yaml @@ -3970,7 +3970,7 @@ components: additionalProperties: false description: >- One action a Bot might take. Who: a Bot, and either the person whose - accounts it runs on or a directory group, for any member of it. What + accounts it runs on or a team or directory group, for any member of it. What starts the run. Then either an app's tool, or something on the Bot's computer. A field that does not apply is empty. required: @@ -3995,7 +3995,9 @@ components: description: The person's id. Empty when a group is named. group: type: string - description: A directory group's name. Empty when a person is named. + description: >- + A directory group's name, or team: for one of the + organization's teams. Empty when a person is named. initiator: $ref: '#/components/schemas/WhatIfInitiator' surface: @@ -4265,6 +4267,19 @@ components: description: The directory groups, by name. items: type: string + teams: + type: array + description: >- + The organization's teams. An action names one in group, as + team:. + items: + type: object + required: [id, name] + properties: + id: + type: string + name: + type: string apps: type: array items: @@ -4295,19 +4310,19 @@ components: enum: [owner, people, team] description: >- Who may steer a Bot that uses a shared app's account: only the Bot's - owner, the people and directory groups named, or everybody in the - organization. + owner, the people, teams and directory groups named, or everyone in + the organization (team). SharedUseMember: type: object - description: One person or directory group an audience names. + description: One person, team or directory group an audience names. required: [kind, value] properties: kind: type: string - enum: [user, group] + enum: [user, group, team] value: type: string - description: The person's id, or the directory group's name. + description: The person's id, the team's id, or the directory group's name. SharedUseApproval: type: object description: >- @@ -4323,7 +4338,7 @@ components: description: Whether runs started by outside input are covered. members: type: array - description: The people and groups named, when the audience is people. Empty otherwise. + description: The people, teams and groups named, when the audience is people. Empty otherwise. items: $ref: '#/components/schemas/SharedUseMember' SharedUseRequest: diff --git a/api/openapi/apps.yaml b/api/openapi/apps.yaml index f99099481e..9450ac56d6 100644 --- a/api/openapi/apps.yaml +++ b/api/openapi/apps.yaml @@ -1,4 +1,4 @@ -# Apps: the apps this OpenBot has added for its Bots to use, the directory of apps it can add, and +# Apps: the apps an organization has added for its Bots to use, the directory of apps it can add, and # how apps are set up here. Also the parts every apps area shares (an app's id, the shared-account # approval, and the refusals about an app), listed in common.yaml for the connections and Bot grants # areas to use. @@ -14,11 +14,12 @@ paths: operationId: listApps summary: List the apps added here description: >- - Return one page of the apps this OpenBot has added for its Bots: the - ones from its catalogue, the ones added from the app directory, and - servers added by their address. Each app comes with the actions it - offers and the Bots that may use each one. Anybody signed in may read - them. Ordered by title, ignoring case, then by id. A missing cursor + Return one page of the apps the organization has added for its Bots: + the ones from OpenBot's catalogue, the ones added from the app + directory, and servers added by their address. Each organization has + its own apps, and an app added in one is not in another. Each app + comes with the actions it offers and the Bots that may use each one. + Any member of the organization may read them. Ordered by title, ignoring case, then by id. A missing cursor starts at the first page and nextCursor null ends the list. security: - webSession: [] @@ -309,12 +310,14 @@ paths: operationId: deleteApp summary: Remove an app description: >- - Remove an app for everybody. Every person's connection to it is ended, + Remove an app for everybody in the organization. Every member's + connection to it is ended, at the app's own service too, every Bot stops being able to use its actions, and a server's key is retired. Recorded on the audit trail. Removing can stop partway when the service behind the app doesn't answer. The app then stays, and removing it again is safe and finishes - the job. Routines can't be removed. Only an administrator may. + the job. Routines can't be removed. Only an administrator of the + organization may. security: - webSession: [] - appOAuth: [apps:write] @@ -401,7 +404,8 @@ paths: summary: Choose whose account an app acts in description: >- Choose whose account an app from the directory acts in: each person's - own (personal), or one account OpenBot holds for everybody (shared). + own (personal), or one account OpenBot holds for everybody in the + organization (shared). Every account the switch leaves behind is ended at the app's service first. Nothing changes unless all of them ended, and the problem's problems then names each account that didn't. Switching to shared @@ -708,9 +712,11 @@ components: additionalProperties: false description: >- Who may have a Bot use an app's one shared account, approved by an - administrator: only the Bot's owner, named people and directory - groups, or everybody; and whether the Bot may act on what people - outside the organization send it. + administrator: only the Bot's owner, named people, teams and + directory groups, or everyone in the organization (team); and whether + the Bot may act on what people outside the organization send it. A + member of kind team names one of the organization's teams by id; a + team of another organization is not found. required: - audience - outsideInput @@ -739,6 +745,7 @@ components: enum: - user - group + - team value: type: string minLength: 1 @@ -815,7 +822,8 @@ components: App: type: object description: >- - An app this OpenBot has added for its Bots, with the actions it offers. + An app the organization has added for its Bots, with the actions it + offers. No secret is ever part of an app: hasCredential says whether a key or client is kept for it. required: @@ -909,7 +917,8 @@ components: - type: 'null' description: >- Whose account an app from the directory acts in: each person's own, - or one account OpenBot holds for everybody. Null for an app with no + or one account OpenBot holds for everybody in the organization. + Null for an app with no account at all, and for any other app. sharedAccountConnected: type: boolean @@ -1095,7 +1104,7 @@ components: AppAccountMode: type: string enum: [personal, shared] - description: Each person's own account, or one account OpenBot holds for everybody. + description: Each person's own account, or one account OpenBot holds for everybody in the organization. AppAccountModeRequest: type: object additionalProperties: false @@ -1138,7 +1147,7 @@ components: enum: [person, deployment] description: >- Whose accounts they are: people's own (person), or the one - OpenBot holds for everybody (deployment). + OpenBot holds for everybody in the organization (deployment). count: type: integer minimum: 0 diff --git a/api/openapi/audit-events.yaml b/api/openapi/audit-events.yaml index b8d357da2a..a3345b79e1 100644 --- a/api/openapi/audit-events.yaml +++ b/api/openapi/audit-events.yaml @@ -11,14 +11,21 @@ paths: operationId: listAuditEvents summary: List audit events description: >- - Return one page of the audit trail, newest first, narrowed by the - filters given. Each filter narrows the events, and a filter that takes + Return one page of the organization's audit trail, newest first, + narrowed by the filters given. Each organization has its own trail, + and an event is on the trail of the organization it happened in. What + happens to the organization itself is on its trail too: + organization.created, organization.renamed, + organization.member_invited, organization.invitation_canceled, + organization.member_joined, organization.member_removed and + organization.member_role_changed. + Each filter narrows the events, and a filter that takes several values separated by commas matches any of them. A value that names nothing in the trail matches no event rather than being refused. A missing cursor starts at the newest event and nextCursor null ends the list. A cursor belongs to the filters that made it, so changing a filter starts again without one; limit may change from page to page. - Only an administrator may read the trail. + Only an administrator of the organization may read its trail. security: - webSession: [] - appOAuth: [audit-events:read] @@ -80,7 +87,8 @@ paths: events; when more match, OpenBot-Export-Truncated says how many it holds, and narrowing the dates exports the rest. A cell a spreadsheet would run as a formula starts with an apostrophe. Each export is - recorded on the trail. Only an administrator may export the trail. + recorded on the trail. Only an administrator of the organization may + export its trail. x-openbot-singleton: true security: - webSession: [] @@ -262,7 +270,8 @@ components: in: query description: >- Events of any of these types, separated by commas, such as - computer.action_refused,mcp.call_rejected. + computer.action_refused,mcp.call_rejected or + organization.member_invited,organization.member_removed. schema: $ref: '#/components/schemas/AuditFilterText' AuditExcludedEventTypes: diff --git a/api/openapi/bot-grants.yaml b/api/openapi/bot-grants.yaml index 64bedab0a9..53c03ef77a 100644 --- a/api/openapi/bot-grants.yaml +++ b/api/openapi/bot-grants.yaml @@ -586,6 +586,99 @@ paths: $ref: './common.yaml#/components/responses/AppDirectoryUnavailable' default: $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/apps/{appId}/team-grants: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: './common.yaml#/components/parameters/AppId' + get: + tags: [Bot grants] + operationId: getAppTeamGrants + summary: Read the teams the app is granted to + description: >- + Return the teams the app is granted to, by id. A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. Only an admin + of the organization may read them. + x-openbot-singleton: true + security: + - webSession: [] + - appOAuth: [bot-grants:read] + - apiKey: [] + responses: + '200': + description: The teams the app is granted to. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/AppTeamGrants' + examples: + granted: + $ref: '#/components/examples/AppTeamGrantsExample' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/AppOrTeamNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + put: + tags: [Bot grants] + operationId: replaceAppTeamGrants + summary: Grant an app to teams + description: >- + Grant the app to exactly these teams of the organization, taking it + from any team left out. An empty list takes it from every team. + A person in one of those teams, or in a team beneath one, may give the app to a Bot they own without an access request, and the Bot may use it only while they stay in such a team; nobody else in the organization may give it to their own Bot. A team of another organization is not found. Only an admin + of the organization may do this. Recorded on the audit trail. + security: + - webSession: [] + - appOAuth: [bot-grants:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AppTeamGrantsInput' + examples: + oneTeam: + value: + teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze] + responses: + '200': + description: The teams the app is now granted to. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/AppTeamGrants' + examples: + granted: + $ref: '#/components/examples/AppTeamGrantsExample' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/AppOrTeamNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/people/{personId}/giveable-apps: parameters: - $ref: './common.yaml#/components/parameters/OrganizationId' @@ -641,8 +734,9 @@ paths: operationId: listAppAccessRequests summary: List requests for apps description: >- - Return one page of the requests waiting for an administrator: all of - them for an administrator, and only their own for anybody else. appId + Return one page of the organization's requests waiting for an + administrator: all of them for an administrator of the organization, + and only their own for anybody else. appId narrows them to one app. Newest first, and by id among requests made at the same moment. A missing cursor starts at the first page and nextCursor null ends the list. @@ -1276,6 +1370,30 @@ components: oneOf: - $ref: '#/components/schemas/BotGrantReplayReport' - type: 'null' + AppTeamGrants: + type: object + description: The teams the app is granted to. + required: [teams] + properties: + teams: + type: array + description: Each team's id, in order. + items: + type: string + AppTeamGrantsInput: + type: object + additionalProperties: false + required: [teams] + properties: + teams: + type: array + maxItems: 100 + description: The id of each team of this organization to grant it to. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ AppAccessRequestKind: type: string description: >- @@ -1648,6 +1766,37 @@ components: retryable: false requestId: req_example traceId: trace_example + AppOrTeamNotFound: + description: >- + OpenBot has no app by that id, a team named is not one of this + organization's, or the organization does not exist. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + app: + value: + type: https://open.bot/errors/app-not-found + title: App not found. + status: 404 + detail: OpenBot has no app called asana. + code: APP_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example BotGrantNotFound: description: >- The Bot isn't one the caller can use, the Bot doesn't have that, or the @@ -2054,6 +2203,10 @@ components: summary: Notion's reads, taken back. value: takenBack: [notion/notion-fetch, notion/notion-search] + AppTeamGrantsExample: + summary: Granted to one team. + value: + teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze] GiveableAppPageExample: summary: Two apps the person could give their Bots. value: diff --git a/api/openapi/bots.yaml b/api/openapi/bots.yaml index 00b055203c..2c41f3da21 100644 --- a/api/openapi/bots.yaml +++ b/api/openapi/bots.yaml @@ -14,9 +14,15 @@ paths: Return one page of the Bots the caller can see: theirs, the ones shared with them, the ones assigned to them and the ones that come with OpenBot, oldest first, and by id among Bots made at the same moment. - hidden=true lists only the Bots the caller hid from their own list - instead. A missing cursor starts at the first page and nextCursor null - ends the list. + Somebody else's private Bot is never among them, an admin's list + included. hidden=true lists only the Bots the caller hid from their own + list instead. scope=organization lists every Bot in the organization, + people's private Bots included, for an admin's screens that decide what + Bots may hold; it is refused to anybody who is not an admin of the + organization. Somebody else's private Bot comes withheld there: its + name and avatar, and nothing from inside it (see the Bot's withheld). + A missing cursor starts at the first page and nextCursor null ends the + list. security: - webSession: [] - appOAuth: [bots:read] @@ -28,6 +34,15 @@ paths: schema: type: boolean default: false + - name: scope + in: query + description: >- + Whose Bots: caller, the Bots the caller can see; organization, every + Bot in the organization, for an admin of it only. + schema: + type: string + enum: [caller, organization] + default: caller - $ref: './common.yaml#/components/parameters/Limit' - $ref: './common.yaml#/components/parameters/Cursor' responses: @@ -1081,7 +1096,8 @@ paths: description: >- Return one page of the published Bots the caller may use or manages: their own publications, the ones published to them by name, to a - group they are in or to the whole team, and the ones an administrator + group or team they are in or to everyone in the organization, and the + ones an administrator assigned them. An administrator sees every one. Who a Team Bot reaches (people, groups and assignments) is shown only to its owner and administrators. Ordered by name, then the Bot's id. A missing cursor @@ -1161,13 +1177,14 @@ paths: put: tags: [Team Bots] operationId: publishTeamBot - summary: Publish a Bot to the team + summary: Publish a Bot to everyone in the organization, or to some of them description: >- - Publish one of the caller's own Bots to the whole team, or to named - people and directory groups, or change who it is published to. Each - person's conversations with it are private to them; its owner can't - read them. Needs the caller's Team Bots switch, and a Bot with a real - name and a description, which is how teammates tell it apart. Every + Publish one of the caller's own Bots to everyone in the organization, + or to named people, teams and directory groups, or change who it is + published to. Each person's conversations with it are private to them; + its owner can't read them. Needs the caller's Team Bots switch, and a + Bot with a real name and a description, which is how the people it is + published to tell it apart. Every person named must have signed in here. Publishing can widen who reaches the shared app accounts the Bot uses, and the answer says which an administrator still has to approve. @@ -1185,7 +1202,7 @@ paths: $ref: '#/components/schemas/TeamBotPublication' examples: team: - summary: To the whole team. + summary: To everyone in the organization. value: audience: team people: @@ -1226,8 +1243,8 @@ paths: operationId: unpublishTeamBot summary: Unpublish a Team Bot description: >- - Stop publishing a Bot: teammates can't use it until it is published - again, and its assignments wait, doing nothing. Its owner or an + Stop publishing a Bot: the people it was published to can't use it + until it is published again, and its assignments wait, doing nothing. Its owner or an administrator may unpublish it. Unpublishing a Bot that is not published changes nothing. security: @@ -1434,7 +1451,8 @@ components: required: true description: >- A directory group, by the name the identity provider gives it, or * - for everybody. + for everybody. A team is written team: followed by the team's id, as + in team:Tm4Qx8LpV2nWc7RbY1sKd0Ze. schema: type: string minLength: 1 @@ -1502,6 +1520,16 @@ components: systemOwned: type: boolean description: Whether it comes with OpenBot rather than belonging to a person. + packageBotId: + type: [string, 'null'] + readOnly: true + description: >- + Which of the Bots an OpenBot starts with this one is, so a client + recognises it in whichever organization it is in. It is the id + that Bot has in the install package: the same as id in the + organization `default`, and the package's id on another + organization's copy, whose own id is generated. Null for a Bot + somebody made. Never accepted when a Bot is created or changed. endpoint: type: [string, 'null'] description: >- @@ -1541,6 +1569,16 @@ components: description: >- Whether the caller created it. Separate from canManage, which is also true for an administrator on everybody's Bots. + withheld: + type: boolean + description: >- + Whether it is somebody else's private Bot, listed for an admin's + screens (listBots with scope=organization) and nothing more. Such + a Bot carries its id, name, avatar and the caller's own state with + it only: title and roleDescription are empty, endpoint is null, + instructions and framework are absent, hasAuth, hasCallbackToken, + isolated, builtIn, runsOnOpenBotModel, keyFromOpenBot and canManage + are false. Absent or false on every other Bot. assignedToMe: type: boolean description: Whether an administrator assigned this Bot to the caller. @@ -2121,12 +2159,14 @@ components: TeamBotAudience: type: string enum: [team, people] - description: team is everybody in the organization; people is the people and groups named. + description: >- + team is everyone in the organization; people is the people, teams and + groups named. TeamBot: type: object description: >- - A Bot published to the team, as the caller sees it. Who it reaches - (people, groups and assignedGroups) is present only for its owner and + A published Bot, as the caller sees it. Who it reaches (people, teams, + groups and assignedGroups) is present only for its owner and administrators. required: - botId @@ -2161,8 +2201,8 @@ components: visibleToTeam: type: boolean description: >- - False while its name or description would leave teammates unable - to tell it apart, so they can't see it. + False while its name or description would leave the people it is + published to unable to tell it apart, so they can't see it. people: type: array description: The people it is published to, by email. @@ -2173,6 +2213,11 @@ components: description: The directory groups it is published to. items: type: string + teams: + type: array + description: The teams it is published to, by each team's id. + items: + type: string assignedGroups: type: array description: The directory groups an administrator assigned it to; * is everybody. @@ -2220,6 +2265,19 @@ components: items: type: string maxLength: 200 + teams: + type: array + maxItems: 100 + description: >- + With people, the teams to publish to, by each team's id. Every + one must be a team of this organization. The people in a team, + and in the teams under it, can use the Bot, and nobody else in + the organization can. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ PublishedTeamBot: type: object required: [teamBot, sharedApps] @@ -2671,7 +2729,7 @@ components: assignedGroups: [] nextCursor: null TeamBotExample: - summary: Published to the whole team, seen by a teammate. + summary: Published to everyone in the organization, seen by one of them. value: teamBot: botId: agent_9b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21 diff --git a/api/openapi/common.yaml b/api/openapi/common.yaml index 172c8ffb29..5ef3decf22 100644 --- a/api/openapi/common.yaml +++ b/api/openapi/common.yaml @@ -27,10 +27,34 @@ info: An OpenBot install holds one or more organizations, and a person may be a - member of several. Every install has the organization `default`, which is - where everybody starts. organizationId is an organization's id or its - slug, and the caller must be a member of it: an organization the caller - is not in answers exactly as one that does not exist. + member of several. Where an install allows more than one, everybody has + an organization of their own, made for them when they first sign in, and + joins others by invitation. Otherwise, and on an install for one person + with no sign-in, everybody works in the organization `default`. + organizationId is an organization's id or its slug, and the caller must + be a member of it: an organization the caller is not in answers exactly + as one that does not exist, `default` included. + + + A program of your own signs its requests in one of two ways. An API key + acts as the person who made it, in every organization they are a member + of, like a personal access token: the address names the organization + each request is for. Keys start `obk_` and are sent as + `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2 + and on the socket a join token is spent on (createConversationJoinToken). + To get a first key, sign in to OpenBot's web app, open Settings, then API + keys, and create one. The key is shown once. Only a person signed in to + the web app can make or delete keys: a key or an app's sign-in cannot. + An app that signs people in uses OAuth 2.1 instead, described under the + appOAuth security scheme: its client ids, redirect addresses, endpoints, + how long tokens last and the four addresses outside /api/v2 a token also + works at. + + + An install for one person on one computer has no sign-in. It signs + nobody in, so it has neither OAuth nor API keys, and the operations + that manage keys and sessions answer 503 with the code + SIGN_IN_UNAVAILABLE. This file is the single source of truth: the clients, the server's types, @@ -47,7 +71,7 @@ tags: - { name: People, description: "The people in the organization: who they are, what they may do, and what is theirs alone (their standing instructions, preferences and first-run onboarding). An administrator sees everybody; anybody else sees themselves, as me." } - { name: Linked accounts, description: "A person's accounts at other services, such as Slack and GitHub, that OpenBot knows are theirs, so a Bot answering there knows who it is talking to." } - { name: Identity providers, description: "The companies' own identity providers registered for single sign-on, by email domain. Only an administrator manages them." } - - { name: API keys, description: "The keys a person makes for automation. A key acts as them, inside the organization, on the API only, and only a person signed in to OpenBot can make or manage one." } + - { name: API keys, description: "The keys a person makes for automation. A key acts as them, in every organization they are a member of, on the API, and only a person signed in to OpenBot can make or manage one." } - { name: Sessions, description: "Where a person is signed in to OpenBot, so they can see each browser and device and sign one out." } - { name: Organization settings, description: "What an administrator sets for everybody, and what this OpenBot offers: sign-in, recording, idle computers, allowlists, the setup checklist, and which models Bots ran on." } - { name: Capabilities, description: "The permission switches that decide what people may do, set for the organization, a role or a directory group, and each person's answer." } @@ -55,9 +79,9 @@ tags: - { name: Conversations, description: "A person's conversations with Bots. What a Bot is doing in one streams over a WebSocket, described in api/asyncapi.yaml; the operations here hand out what that socket needs." } - { name: Tasks, description: "The work a Bot does for a person in a conversation of its own: started from something a check-in found, or handed to the Bot by another. Where a task stands is read from its conversation, never stored." } - { name: Voice, description: "Voice calls with a conversation's Bot: how a call connects, and the calls a person saved in a conversation with their transcripts." } - - { name: Credentials, description: "The vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them." } + - { name: Credentials, description: "The organization's vault: the model keys, app keys and app tokens OpenBot keeps encrypted for its Bots. A secret goes in and is never read back out. Only an administrator manages them." } - { name: Models, description: "The models Bots can run on, and the one a person chose for each of their conversations." } - - { name: Apps, description: "The apps this OpenBot has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here." } + - { name: Apps, description: "The apps the organization has added for its Bots to use, from the directory of apps it can add or by a server's address, and how apps are set up here." } - { name: Connections, description: "A person's connections to apps: the accounts they signed in with so their Bots can act there for them, and an app's one shared account when an administrator connects it for everybody." } - { name: Bot grants, description: "What each Bot may use: the app actions, skills and other Bots it was given, and each app as it stands for the person asking." } - { name: App access requests, description: "A person asking an administrator to turn an app on, give it to a Bot, or connect its shared account." } @@ -72,6 +96,7 @@ tags: - { name: Goals, description: "A person's goals: an outcome a Bot works toward, run on request, on a routine's schedule or when an outside event arrives through one of the goal's triggers." } - { name: Follow-ups, description: "Work a Bot scheduled for itself to come back to later in a conversation." } - { name: Organizations, description: "The organizations the caller is a member of, and each one's members. An organization keeps its own Bots and conversations, apart from every other's." } + - { name: Teams, description: "An organization's teams: named groups of its members, and each team's people. What is granted to a team is its people's to use, and nobody else's in the organization. A team is made here or kept in step with a group of the company's directory." } - { name: Approvals, description: "What a person's Bots are waiting on them for: the actions that ask before they run, the questions a Bot asked, and what the person set for themselves about asking (their preferences, their own rules, and what they allowed for one conversation). Each person's are theirs alone." } - { name: Approval rules, description: "The organization's approval rules: which actions every member's Bots take without asking, ask a person about first, or hand to the person. An administrator can describe rules in English, test them against what Bots already did, and save several as one change." } - { name: Reviewer guidance, description: "What an administrator tells auto-review, in plain English: what to ask about and what is routine for the organization. Checked by an independent reading before it is saved, and never able to switch built-in safety off." } @@ -196,6 +221,7 @@ paths: /api/v2/organizations/{organizationId}/bots/{botId}/apps/{appId}/give: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1apps~1{appId}~1give' } /api/v2/organizations/{organizationId}/bots/{botId}/apps/{appId}/take-back: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1apps~1{appId}~1take-back' } /api/v2/organizations/{organizationId}/bots/{botId}/apps/{appId}/approve: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1apps~1{appId}~1approve' } + /api/v2/organizations/{organizationId}/apps/{appId}/team-grants: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1apps~1{appId}~1team-grants' } /api/v2/organizations/{organizationId}/people/{personId}/giveable-apps: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1giveable-apps' } /api/v2/organizations/{organizationId}/app-access-requests: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1app-access-requests' } /api/v2/organizations/{organizationId}/app-access-requests/{appAccessRequestId}: { $ref: './bot-grants.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1app-access-requests~1{appAccessRequestId}' } @@ -215,6 +241,7 @@ paths: /api/v2/organizations/{organizationId}/bots/{botId}/components/{componentId}/call: { $ref: './components.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1components~1{componentId}~1call' } /api/v2/organizations/{organizationId}/skills: { $ref: './skills.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1skills' } /api/v2/organizations/{organizationId}/skills/{skillId}: { $ref: './skills.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1skills~1{skillId}' } + /api/v2/organizations/{organizationId}/skills/{skillId}/team-grants: { $ref: './skills.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1skills~1{skillId}~1team-grants' } /api/v2/organizations/{organizationId}/people/{personId}/devices: { $ref: './notifications.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1devices' } /api/v2/organizations/{organizationId}/people/{personId}/devices/{deviceId}: { $ref: './notifications.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1devices~1{deviceId}' } /api/v2/organizations/{organizationId}/people/{personId}/destinations: { $ref: './notifications.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1destinations' } @@ -257,6 +284,18 @@ paths: /api/v2/organizations/{organizationId}/bots/{botId}/follow-ups/{followUpId}/cancel: { $ref: './schedules.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1bots~1{botId}~1follow-ups~1{followUpId}~1cancel' } /api/v2/people/me/organizations: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1organizations' } /api/v2/organizations/{organizationId}/members: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1members' } + /api/v2/organizations/{organizationId}/profile: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1profile' } + /api/v2/organizations/{organizationId}/members/{personId}: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1members~1{personId}' } + /api/v2/organizations/{organizationId}/invitations: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1invitations' } + /api/v2/organizations/{organizationId}/invitations/{invitationId}: { $ref: './organizations.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1invitations~1{invitationId}' } + /api/v2/people/me/invitations: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations' } + /api/v2/people/me/invitations/{invitationId}: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations~1{invitationId}' } + /api/v2/people/me/invitations/{invitationId}/accept: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations~1{invitationId}~1accept' } + /api/v2/people/me/invitations/{invitationId}/decline: { $ref: './organizations.yaml#/paths/~1api~1v2~1people~1me~1invitations~1{invitationId}~1decline' } + /api/v2/organizations/{organizationId}/teams: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams' } + /api/v2/organizations/{organizationId}/teams/{teamId}: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams~1{teamId}' } + /api/v2/organizations/{organizationId}/teams/{teamId}/members: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams~1{teamId}~1members' } + /api/v2/organizations/{organizationId}/teams/{teamId}/members/{memberId}: { $ref: './teams.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1teams~1{teamId}~1members~1{memberId}' } /api/v2/organizations/{organizationId}/people/{personId}/approvals: { $ref: './approvals.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1approvals' } /api/v2/organizations/{organizationId}/people/{personId}/approvals/{approvalId}/decide: { $ref: './approvals.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1approvals~1{approvalId}~1decide' } /api/v2/organizations/{organizationId}/people/{personId}/questions: { $ref: './approvals.yaml#/paths/~1api~1v2~1organizations~1{organizationId}~1people~1{personId}~1questions' } @@ -424,6 +463,63 @@ components: description: >- Desktop and mobile. OAuth 2.1 authorization code with PKCE (RFC 7636, S256 only); the access token is sent as a bearer token. + + + Clients. Three public clients are registered: `openbot-desktop-oauth`, + `openbot-mobile` and `openbot-cli`. A public client has no secret and + must use PKCE with S256. Dynamic client registration is off, so an + app uses one of these ids. + + + Redirect addresses. A client on the person's own computer listens on + a loopback address and any port: + `http://127.0.0.1:/callback` or + `http://[::1]:/callback`. `localhost` is not accepted. + + + Endpoints. The authorization server's metadata (RFC 8414) is at + `/.well-known/oauth-authorization-server/api/auth`. The person is + sent to `/api/auth/oauth2/authorize`. The code is exchanged, and a + token refreshed, at `/api/auth/oauth2/token`, with a form-encoded + body (`application/x-www-form-urlencoded`) that carries `client_id` + and no secret: the token and revocation endpoints take no client + authentication (`none` in the metadata's + `token_endpoint_auth_methods_supported`). A wrong `code_verifier` is + answered 400 `invalid_grant`, and the code cannot be used again. A + token is revoked (RFC 7009) at `/api/auth/oauth2/revoke`; revoking a + token the server does not know, or one already revoked, answers 200. + + + Tokens. An access token starts `oba_` and lasts one hour. A refresh + token starts `obr_`, is issued only when the `offline_access` scope + is asked for, and rotates on every use: each refresh answers a new + refresh token and ends the one it was given. Access tokens work on + /api/v2, and on four addresses outside it that an app's screens need, + each with the scope given: `GET /api/me`, who is signed in + (people:read); the chat runtime at `/api/copilotkit` and everything + under it (conversations:write); a file's download at + `GET /api/attachments/{attachmentId}`, the address a sent message + keeps (conversations:read); and the relayed realtime socket at + `/api/intelligence/client/websocket` (conversations:read). They work + nowhere else. + + + Organization. An access token carries no memory of which + organization the person is working in. An address under + `/api/v2/organizations/{organizationId}` names it. Where an address + names none, such as the list of the person's own organizations, an + app sends the header `OpenBot-Organization` with the organization's + id. It is checked against the person's membership on every request, + and an organization they are not in answers not found. With no + header, the app works in the person's own organization. + + + Consent. The person is asked once for each app, and not again for + scopes they already allowed it. + + + An install for one person on one computer has no sign-in, so it has + no OAuth: there is nobody to authorize an app as. flows: authorizationCode: authorizationUrl: /api/auth/oauth2/authorize @@ -462,7 +558,7 @@ components: model-catalogue:read: Read the models Bots can run on. model-choices:read: Read the model the signed-in person chose for each of their conversations. model-choices:write: Choose the model the signed-in person's conversations answer on. - apps:read: Read the apps this OpenBot has added, the directory of apps it can add, and how apps are set up here. + apps:read: Read the apps the organization has added, the directory of apps it can add, and how apps are set up here. apps:write: Add, change, refresh and remove apps, when the signed-in person may. connections:read: Read the signed-in person's connections to apps, and each app's shared account. connections:write: Connect and disconnect the signed-in person's apps, and an app's shared account when the signed-in person is an administrator. @@ -514,8 +610,15 @@ components: scheme: bearer bearerFormat: OpenBot API key description: >- - Automation. An API key acts as the person who created it, inside one - organization. + Automation. An API key acts as the person who created it, in every + organization they are a member of, like a personal access token: the + address of each request names the organization, and one the person + is not in answers not found. A key starts `obk_` and is sent as + `Authorization: Bearer ` or in an `x-api-key` header, on /api/v2 + and on the relayed realtime socket at + `/api/intelligence/client/websocket`, where a join token the key made + is spent (createConversationJoinToken). A person makes one in the web + app, signed in, under Settings, then API keys (createApiKey). recorderConnection: type: http scheme: bearer @@ -534,8 +637,8 @@ components: in: path required: true description: >- - The organization, by its id or its slug. Every install has one - addressed as `default`. + The organization, by its id or its slug. One the caller is not a + member of answers as one that does not exist, `default` included. schema: type: string minLength: 1 diff --git a/api/openapi/components.yaml b/api/openapi/components.yaml index 5b0723ff65..5f41314be2 100644 --- a/api/openapi/components.yaml +++ b/api/openapi/components.yaml @@ -11,8 +11,12 @@ paths: operationId: listComponents summary: List components description: >- - Return one page of the components Bots draw in conversations: charts, - cards and the ones an admin wrote in Playground. An admin sees every + Return one page of the components the organization's Bots draw in + conversations: charts, cards and the ones an admin wrote in + Playground. Each organization has its own: what a component tells the + model, whether it is published, which Bots may draw it and which data + it may read are decided in one organization and change nothing in + another. An admin of the organization sees every component with its draft, the Bots held back from it and the data it may read. Anybody else sees the published ones only, and those fields are null. kind=playground lists only the components written in @@ -61,14 +65,15 @@ paths: summary: Announce the components the app can draw description: >- Tell OpenBot which components this version of the app can draw. A - component OpenBot has not seen before is added and published, so - every Bot can draw it at once. One it already has is left exactly as - it is: what it tells the model, whether it is published and who may - use it were decided here. A description nobody here has edited - follows the one this version of OpenBot ships. In OpenBot Personal a - component is also given the data it reads. Anybody signed in may - announce, and the web app does it on every load. The whole list is - refused if one entry is missing a field. + component the organization has not seen before is added and + published, so every one of its Bots can draw it at once. One it + already has is left exactly as it is: what it tells the model, + whether it is published and who may use it were decided here. A + description nobody here has edited follows the one this version of + OpenBot ships. In OpenBot Personal a component is also given the data + it reads. Anybody signed in may announce, and the web app does it on + every load. The whole list is refused if one entry is missing a field + or has a name that starts with @. security: - webSession: [] - appOAuth: [components:write] @@ -95,7 +100,7 @@ paths: description: Show how many actions each Bot took recently. responses: '200': - description: The components this announcement added. Empty when OpenBot had them all. + description: The components this announcement added. Empty when the organization had them all. headers: Cache-Control: $ref: './common.yaml#/components/headers/PrivateNoStore' @@ -990,7 +995,7 @@ components: type: string minLength: 1 pattern: \S - description: The tool name a Bot draws it by. Trimmed. + description: The tool name a Bot draws it by. Trimmed. It can't start with @. title: type: string minLength: 1 @@ -1190,13 +1195,24 @@ components: A field is missing or blank once trimmed, holds text that can't be kept, or doesn't fit this kind of component: a title or source for one that comes with OpenBot, a Playground name that isn't custom_ and - lower-case letters, numbers and underscores, or a data function this - OpenBot doesn't ship. + lower-case letters, numbers and underscores, an announced name that + starts with @, or a data function this OpenBot doesn't ship. content: application/problem+json: schema: $ref: './common.yaml#/components/schemas/Problem' examples: + nameStartsWithAt: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: Component at index 0 has a name that starts with @, which a component's name can't. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example announcement: value: type: https://open.bot/errors/validation-error diff --git a/api/openapi/computers.yaml b/api/openapi/computers.yaml index 7789bb8857..067d2d6cb1 100644 --- a/api/openapi/computers.yaml +++ b/api/openapi/computers.yaml @@ -11,10 +11,12 @@ paths: operationId: listComputers summary: List the organization's computers description: >- - Return one page of the computers Bots run on: each person's, and each - isolated Bot's. Where every person's Bots share one computer, each - entry is one person's seat on one Bot there. Ordered by whose computer - it is, then by Bot. Only an administrator may read them. A missing + Return one page of the computers the organization's Bots run on: each + person's, and each isolated Bot's. Where every person's Bots share one + computer, each entry is one person's seat on one Bot there. A computer + another organization's Bots run on is never listed. Ordered by whose + computer it is, then by Bot. Only an administrator of the organization + may read them. A missing cursor starts at the first page and nextCursor null ends the list. security: - webSession: [] @@ -61,8 +63,9 @@ paths: Stop one computer from the list now, and record it on the audit trail. Its files and sign-ins stay, and it starts again when a Bot next needs it. The computer is named by whose it is, person: or bot:; - botId names one Bot's seat on a shared computer. Only an administrator - may do this. + botId names one Bot's seat on a shared computer. A computer that is + not one of the organization's is not found. Only an administrator of + the organization may do this. security: - webSession: [] - appOAuth: [computers:write] @@ -99,7 +102,7 @@ paths: '403': $ref: './common.yaml#/components/responses/AdminOnly' '404': - $ref: './common.yaml#/components/responses/OrganizationNotFound' + $ref: '#/components/responses/OrganizationComputerNotFound' '409': $ref: './common.yaml#/components/responses/IdempotencyConflict' '500': @@ -119,7 +122,8 @@ paths: Delete one computer's browser profile, and every sign-in with it, and record it on the audit trail. The computer is named by whose it is, person: or bot:; botId names one Bot's seat on a shared - computer. Only an administrator may do this. + computer. A computer that is not one of the organization's is not + found. Only an administrator of the organization may do this. security: - webSession: [] - appOAuth: [computers:write] @@ -156,7 +160,7 @@ paths: '403': $ref: './common.yaml#/components/responses/AdminOnly' '404': - $ref: './common.yaml#/components/responses/OrganizationNotFound' + $ref: '#/components/responses/OrganizationComputerNotFound' '409': $ref: './common.yaml#/components/responses/IdempotencyConflict' '500': @@ -176,7 +180,8 @@ paths: Move one computer onto the image this OpenBot now runs, and record it on the audit trail. Files and sign-ins stay; a running computer restarts. The computer is named by whose it is, person: or - bot:. Only an administrator may do this. + bot:. A computer that is not one of the organization's is not + found. Only an administrator of the organization may do this. security: - webSession: [] - appOAuth: [computers:write] @@ -213,7 +218,7 @@ paths: '403': $ref: './common.yaml#/components/responses/AdminOnly' '404': - $ref: './common.yaml#/components/responses/OrganizationNotFound' + $ref: '#/components/responses/OrganizationComputerNotFound' '409': $ref: './common.yaml#/components/responses/IdempotencyConflict' '500': @@ -2150,7 +2155,8 @@ components: Computer: type: object description: >- - One computer as an administrator sees it: a person's, or an isolated + One of the organization's computers as its administrator sees it: a + person's, or an isolated Bot's. Where every person's Bots share one computer, one person's seat on one Bot there. required: [id, computer, kind, running, startedAt] @@ -2338,6 +2344,37 @@ components: retryable: false requestId: req_example traceId: trace_example + OrganizationComputerNotFound: + description: >- + The computer named is not one of the organization's Bots' computers, + or the organization does not exist. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + computer: + value: + type: https://open.bot/errors/bot-not-found + title: Bot not found. + status: 404 + detail: Couldn't find that computer. + code: BOT_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + organization: + value: + type: https://open.bot/errors/organization-not-found + title: Organization not found. + status: 404 + detail: Couldn't find that organization. + code: ORGANIZATION_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example ComputerBotNotFound: description: >- The Bot does not exist or is not the caller's to use, a file or a diff --git a/api/openapi/connections.yaml b/api/openapi/connections.yaml index 8225180f74..b4f1576315 100644 --- a/api/openapi/connections.yaml +++ b/api/openapi/connections.yaml @@ -1,5 +1,5 @@ # Connections: a person's connections to apps, the accounts they connected at each, and the consent -# for one action; and an app's one shared account, which an administrator connects for everybody. +# for one action; and an app's one shared account, which an administrator connects for the organization. # # One area of OpenBot's REST API. `bun run api:bundle` joins every area with common.yaml into # api/openapi.yaml, the file every client and check reads. See api/README.md. @@ -659,9 +659,11 @@ paths: operationId: getSharedConnection summary: Read an app's shared account description: >- - Return the one account an app in Shared mode acts as for everybody: - whether it is connected, who connected it, and the app's own name - for the account. Anybody signed in may read it. Not found when the + Return the one account an app in Shared mode acts as for everybody in + the organization: whether it is connected, who connected it, and the + app's own name for the account. Each organization connects its own, + and one organization's shared account is never used in another. Any + member of the organization may read it. Not found when the app is connected by each person instead, as getConnection reads. x-openbot-singleton: true security: @@ -703,13 +705,15 @@ paths: summary: Start connecting an app's shared account description: >- Start connecting the one account an app in Shared mode acts as for - everybody, and say what happens next, as connectApp does: consent + everybody in the organization, and say what happens next, as + connectApp does: consent answers the address of the app's sign-in page, form answers the boxes to fill in, connected means it is connected already. The person comes back to the app's page, where confirmSharedConnection checks the result. Where an app connects once, a shared account already connected - is a conflict: disconnect it first. Only an administrator may connect - it. The address and the values are never logged. + is a conflict: disconnect it first. Only an administrator of the + organization may connect it. The address and the values are never + logged. security: - webSession: [] - appOAuth: [connections:write] diff --git a/api/openapi/conversations.yaml b/api/openapi/conversations.yaml index a65852d44a..42247c3c9e 100644 --- a/api/openapi/conversations.yaml +++ b/api/openapi/conversations.yaml @@ -74,7 +74,11 @@ paths: once and for about half a minute, so ask for a new one for every connection, and again to reconnect. Only a person in the conversation may have one, and it opens the thread they see there and no other. A - conversation no Bot has run in yet has nothing to join. + conversation no Bot has run in yet has nothing to join (409). Where + realtime.clientUrl is on this server, open it with the same + credential that made the token: the session, an app's access token, + or an API key, as Authorization: Bearer or x-api-key. So a script + that holds only an API key can watch a conversation live. security: - webSession: [] - appOAuth: [conversations:read] @@ -1687,11 +1691,18 @@ components: minLength: 1 description: >- The socket's address, without the /websocket it ends in or its - query. A ws or wss address, or a path on this server. + query. A ws or wss address, or a path on this server, which is + resolved against the address the API was called at. Where it + is on this server, the socket is opened with the credential + that made the token (see createConversationJoinToken). topic: type: string pattern: ^thread:.+$ - description: The topic to join on the socket, thread:{threadId}. + description: >- + The topic to join on the socket, as the realtime gateway knows + the thread. Use it as given: outside the organization default + it does not name threadId, so a topic made from threadId joins + nothing. Conversation: type: object description: A conversation between the caller and one or more Bots. @@ -2240,7 +2251,9 @@ components: properties: id: type: string - description: The caller's own id for the message, so a retry is the same message. + description: The caller's own id for the message, any string, so a retry in the + same conversation is the same message. The conversation's messages + list it under this id. minLength: 1 maxLength: 160 text: @@ -2313,6 +2326,12 @@ components: threadId: type: string description: The new thread's id. + liveThreadId: + type: string + description: The id that live updates about this thread carry. Compare + an incoming update with this one, and use threadId everywhere else. + It is threadId itself in the organization default. Left out by a + server that names threads one way only, where it is threadId. ConversationThreadStatus: type: object required: @@ -2324,6 +2343,12 @@ components: known: type: boolean description: Whether the thread still holds the caller's conversation. + liveThreadId: + type: string + description: The id that live updates about this thread carry. Compare + an incoming update with this one, and use threadId everywhere else. + It is threadId itself in the organization default. Left out by a + server that names threads one way only, where it is threadId. TaskStatus: type: string enum: @@ -3068,10 +3093,10 @@ components: value: {"transport": "webrtc"} ConversationThreadExample: summary: "A new thread id." - value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a"} + value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "liveThreadId": "2b503bf7-514a-8c4e-b132-3ca9b729ffeb"} ConversationThreadStatusExample: summary: "A thread that is still there." - value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "known": true} + value: {"threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "known": true, "liveThreadId": "2b503bf7-514a-8c4e-b132-3ca9b729ffeb"} TaskPageExample: summary: "One task, ready to read." value: {"tasks": [{"id": "7c2d6b1f-6f10-4a53-9d51-5f0d6c0e2f1a", "botId": "general-assistant", "conversationId": "5f0d6c0e-2f1a-4a53-9d51-6f3d6b1f6f10", "threadId": "6f3d6b1f-6f10-8a53-9d51-5f0d6c0e2f1a", "title": "Reply to Sam about the spec", "why": "Sam asked for the spec by Friday.", "origin": "check_in", "suggestionId": "0b1c6f0e-7f0e-4c1e-9d55-2f4a8c1b6e21", "sourceApp": "Gmail", "sourceLink": null, "originConversationId": null, "status": "ready_for_review", "failure": null, "failedAt": null, "stoppedAt": null, "next": "Read the draft and send it.", "workingSince": null, "lastActivityAt": "2026-11-14T09:05:00.000Z", "resolvedAt": null, "createdAt": "2026-11-14T09:00:00.000Z", "updatedAt": "2026-11-14T09:05:00.000Z"}], "nextCursor": null} diff --git a/api/openapi/learning.yaml b/api/openapi/learning.yaml index 112758d1e6..2ce6b66580 100644 --- a/api/openapi/learning.yaml +++ b/api/openapi/learning.yaml @@ -4,7 +4,10 @@ # api/openapi.yaml, the file every client and check reads. See api/README.md. # # CopilotKit Intelligence learns skills from conversations and recordings, in Learning spaces -# (containers) inside the organization's Intelligence project. What it proposes, the evidence behind +# (containers) that belong to one organization. Every organization has its own spaces, and each +# person has their own space in each organization they belong to: what is learned in one +# organization never reaches a Bot in another, the same person's Bots included, and "every Bot" +# below always means every Bot in the organization. What it proposes, the evidence behind # each proposal, approving and rejecting one, and its runs live in Intelligence: OpenBot reads and # changes them for a person, after checking which spaces that person may reach, and answers in the # shapes below. Beside them is what OpenBot keeps: which space each Bot learns into, who reviews @@ -14,6 +17,7 @@ # The organization's spaces (the one every Bot learns into, and each Bot's own) are an # administrator's, under settings/learning, picked with botId. A person's own spaces are under # people/{personId}, picked with containerId; an administrator may read and review them too. +# An administrator here is an administrator of the organization in the address, and of no other. paths: /api/v2/organizations/{organizationId}/settings/learning: parameters: @@ -1800,6 +1804,19 @@ components: oneOf: - $ref: '#/components/schemas/LearningAutomatic' - type: 'null' + organizationSpaceId: + description: >- + The space OpenBot keeps for this organization alone, which its + Bots learn into unless an administrator chooses another. Another + space of the organization's is named after it: this id, a hyphen, + then a name of the administrator's choosing. The id says nothing + a person can read, so a screen names the space by the + organization and never shows it. Null, or absent, where OpenBot + keeps no space for the organization alone and its default is + whichever space is assigned or chosen. + oneOf: + - $ref: '#/components/schemas/LearningSpaceId' + - type: 'null' LearningAutomaticResult: type: object required: [automatic] @@ -2040,8 +2057,9 @@ components: enum: [closed, open, choose] description: >- Who else's Bots use the skills learned in a person's own space. - closed: only their own Bots. open: every Bot. choose: every Bot, for - the skills they open one by one. + closed: only their own Bots. open: every Bot in the organization. + choose: every Bot in the organization, for the skills they open one + by one. Never a Bot in another organization. PersonalLearnedSkill: type: object required: [name, description, open, approvedBy, sharing] diff --git a/api/openapi/memory.yaml b/api/openapi/memory.yaml index 927ed23fac..1610c1965e 100644 --- a/api/openapi/memory.yaml +++ b/api/openapi/memory.yaml @@ -9,6 +9,10 @@ # does the recall, and the memories Intelligence holds for the person that OpenBot formed no record # of are listed here too. Without it, OpenBot's record is the whole store. A single-person OpenBot # keeps no memory: every operation here answers not found there. +# +# A person's memory is kept per organization. What their Bots remember in one organization is never +# listed or recalled in another they belong to, and a memory named from another organization is +# answered as not found. paths: /api/v2/organizations/{organizationId}/people/{personId}/memories: parameters: @@ -19,8 +23,9 @@ paths: operationId: listMemories summary: List a person's memories description: >- - Return one page of what a person's Bots remember about them, most - recently changed first: the ones they wrote, the ones their Bots + Return one page of what a person's Bots remember about them in this + organization, and in no other they belong to, most recently changed + first: the ones they wrote, the ones their Bots formed and are waiting for their review, the ones read in from their sources, and the ones the backend holds for them that OpenBot formed no record of, after OpenBot's own. Paused memories are included; diff --git a/api/openapi/model-connections.yaml b/api/openapi/model-connections.yaml index 237de7bcbc..e42d9df16a 100644 --- a/api/openapi/model-connections.yaml +++ b/api/openapi/model-connections.yaml @@ -11,10 +11,13 @@ paths: operationId: listCredentials summary: List the credentials in the vault description: >- - Return one page of the credentials the vault keeps, live and revoked, - oldest first. A credential says what it is for and whether it is live, - and never holds its secret: nothing in the API reads a secret back out. - Only an administrator may list them. A missing cursor starts at the + Return one page of the credentials the organization's vault keeps, + live and revoked, oldest first. Each organization has its own vault, + and another organization's credentials are never listed. A credential + says what it is for and whether it is live, and never holds its + secret: nothing in the API reads a secret back out. Only an + administrator of the organization may list them. A missing cursor + starts at the first page and nextCursor null ends the list. security: - webSession: [] @@ -55,13 +58,14 @@ paths: operationId: createCredential summary: Add a credential to the vault description: >- - Encrypt a secret and keep it in the vault under one key: a kind, a + Encrypt a secret and keep it in the organization's vault under one + key: a kind, a provider and a key id. A key holds one live credential, so adding one for a key that already has one replaces it, and the one it replaces is revoked in the same write. A model key sent without a key id is filed under the name OpenBot's own Bots read (getModelKey). The secret is write-only: no answer includes it, now or later. Recorded on the audit - trail. Only an administrator may add one. + trail. Only an administrator of the organization may add one. security: - webSession: [] - appOAuth: [credentials:write] @@ -120,8 +124,9 @@ paths: description: >- Stop a live credential being used, and keep its record. Nothing reads a revoked credential again. Recorded on the audit trail. Only an - administrator may revoke one. One that does not exist, or is revoked - already, is not found. + administrator of the organization may revoke one. One that does not + exist, is in another organization's vault, or is revoked already, is + not found. security: - webSession: [] - appOAuth: [credentials:write] @@ -166,9 +171,9 @@ paths: summary: Read where the Bots find their model key description: >- Return the provider OpenBot's own Bots run on, the key id their model - key is filed under in the vault, and whether a live key is kept there. - Never the key. A model key added without a key id is filed here. Only - an administrator may read it. + key is filed under in the organization's vault, and whether a live key + is kept there. Never the key. A model key added without a key id is + filed here. Only an administrator of the organization may read it. x-openbot-singleton: true security: - webSession: [] @@ -394,7 +399,8 @@ components: Credential: type: object description: >- - A credential in the vault as the API shows it: what it is for and + A credential in the organization's vault as the API shows it: what it + is for and whether it is live. Never its secret, which only ever goes in. required: [id, kind, provider, keyId, metadata, createdAt, revokedAt] properties: diff --git a/api/openapi/notifications.yaml b/api/openapi/notifications.yaml index 47961a5b3b..2c82710924 100644 --- a/api/openapi/notifications.yaml +++ b/api/openapi/notifications.yaml @@ -160,7 +160,11 @@ paths: Return one page of the places outside OpenBot a person continues their conversations with Bots: a Slack or Microsoft Teams chat, or a phone number for text messages, each tied to one conversation with - one Bot. The first connected first. Only the person themselves may + one Bot. A Slack account, a Teams account or a phone number is + connected in one organization at a time: connecting one that is + connected in another organization answers 400 until it is + disconnected there. The first connected first. Only the person + themselves may list them; there is no administrator view. A missing cursor starts at the first page and nextCursor null ends the list. security: @@ -1191,13 +1195,25 @@ components: description: >- The request doesn't match the API, the conversation isn't the person's or the Bot isn't in it, a phone's verification expired, was - used already or its code was wrong, or the phone is connected to - another person. + used already or its code was wrong, the phone is connected to + another person, or the Slack account, Teams account or phone is + connected in another organization. content: application/problem+json: schema: $ref: './common.yaml#/components/schemas/Problem' examples: + connectedInAnotherOrganization: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: That account is already connected to OpenBot in another organization. Disconnect it there, then connect it here. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example notTheirs: value: type: https://open.bot/errors/validation-error diff --git a/api/openapi/organizations.yaml b/api/openapi/organizations.yaml index 15941070d3..7b2078f78c 100644 --- a/api/openapi/organizations.yaml +++ b/api/openapi/organizations.yaml @@ -12,11 +12,19 @@ paths: Return one page of the organizations the caller is a member of, the one they joined first at the top, each with the caller's role in it. active marks the one the caller's session is working in, which is - where every address outside /api/v2 reads and writes; a request - signed in with an API key or an app's token has no session, so none - is active. To work in another one, set it as the session's active - organization (POST /api/auth/organization/set-active). A missing - cursor starts at the first page and nextCursor null ends the list. + where every address outside /api/v2 reads and writes. A request + signed in with an API key has no session, so none is active. An + app's token has no session either: for it, active marks the + organization its OpenBot-Organization header names, or the caller's + own when it sends none. The header is checked against the caller's + membership, as on every address that names no organization, so one + they are not in answers not found. A session and an API key ignore + it. To work in another one, set it as the + session's active organization + (POST /api/auth/organization/set-active). Made with an app's token, + that call checks that the caller is a member, stores nothing and + answers the organization. A missing cursor starts at the first page + and nextCursor null ends the list. security: - webSession: [] - appOAuth: [organizations:read] @@ -24,6 +32,19 @@ paths: parameters: - $ref: './common.yaml#/components/parameters/Limit' - $ref: './common.yaml#/components/parameters/Cursor' + - name: OpenBot-Organization + in: header + required: false + description: >- + For a request signed in with an app's token: the organization it + works in, by id or slug, which the list marks active. Without it + the caller's own is active. One the caller is not a member of + answers not found, and one that is not a single id or slug 400. + Ignored for a session and an API key. + schema: + type: string + minLength: 1 + maxLength: 200 responses: '200': description: One page of organizations. @@ -43,6 +64,8 @@ paths: $ref: './common.yaml#/components/responses/Unauthenticated' '403': $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' '500': $ref: './common.yaml#/components/responses/ServerError' default: @@ -52,11 +75,13 @@ paths: operationId: createOrganization summary: Create an organization description: >- - Create an organization with the caller as its owner. It starts with no - Bots and no conversations. Who may create one is the deployment's - choice: its admins (the admins of `default`) unless it lets anybody - signed in. Without a slug, one is made from the name. The caller's - session keeps working where it was. A repeated request with the same + Create an organization with the caller as its owner. It starts with + what a fresh install starts with, its starter Bots included, and no + conversations. Everybody already has an organization of + their own, made when they first signed in; this is for making another, + which anybody signed in may do where OpenBot keeps more than one. + Without a slug, one is made from the name. The caller's session keeps + working where it was. A repeated request with the same Idempotency-Key and body returns the first result. security: - webSession: [] @@ -93,7 +118,7 @@ paths: '401': $ref: './common.yaml#/components/responses/Unauthenticated' '403': - $ref: './common.yaml#/components/responses/AdminOnly' + $ref: './common.yaml#/components/responses/Forbidden' '409': $ref: '#/components/responses/OrganizationConflict' '500': @@ -102,6 +127,63 @@ paths: $ref: '#/components/responses/OrganizationNotCreated' default: $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/profile: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + patch: + tags: [Organizations] + operationId: updateOrganization + summary: Rename an organization + description: >- + Give the organization a new name. Its id and its slug stay as they + are, so every address that names it keeps working. An organization + OpenBot named after its person stops following what that person is + called once it has been renamed. Only an owner or an admin of this + organization can. A repeated request with the same Idempotency-Key + and body returns the first result. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationRequest' + examples: + renamed: + value: + name: Acme Research Lab + responses: + '200': + description: The organization, renamed. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationResponse' + examples: + renamed: + $ref: '#/components/examples/RenamedOrganization' + '400': + $ref: '#/components/responses/InvalidOrganization' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' /api/v2/organizations/{organizationId}/members: parameters: - $ref: './common.yaml#/components/parameters/OrganizationId' @@ -145,15 +227,164 @@ paths: $ref: './common.yaml#/components/responses/ServerError' default: $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/members/{personId}: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: './common.yaml#/components/parameters/PersonId' + patch: + tags: [Organizations] + operationId: updateOrganizationMember + summary: Change a member's role + description: >- + Give a member of the organization another role. An owner or an admin + changes anybody between admin and member. Only an owner makes + somebody an owner, or changes an owner's role, their own included, + and the organization always keeps an owner: the last one cannot step + down. A person's own organization keeps exactly its one owner. The + members list says which roles the caller may give each member, as + assignableRoles. A repeated request with the same Idempotency-Key + and body returns the first result. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateOrganizationMemberRequest' + examples: + owner: + value: + role: owner + responses: + '200': + description: The member, with their new role. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationMemberResponse' + examples: + owner: + $ref: '#/components/examples/PromotedOrganizationMember' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: './common.yaml#/components/responses/PersonNotFound' + '409': + $ref: '#/components/responses/OwnerStays' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + delete: + tags: [Organizations] + operationId: removeOrganizationMember + summary: Remove a member, or leave an organization + description: >- + End somebody's membership of the organization. An owner or an admin + of it can remove anybody whose membership can end, and any such + member can leave by naming themselves or `me`. The owner stays, so + nobody leaves their own organization, and so does somebody this + OpenBot's settings keep as an admin of it. The person keeps their account and their + other organizations, and what they made here stays here. Removing + somebody who is not a member answers the same as removing one. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '204': + description: They are not a member. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/OwnerStays' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/invitations: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + get: + tags: [Organizations] + operationId: listOrganizationInvitations + summary: List the invitations an organization has sent + description: >- + Return one page of the organization's invitations that have not been + accepted or canceled, the newest first: the ones still waiting, the + ones that expired and the ones that were declined. Only an owner or an + admin of this organization can read it. A missing cursor starts at the + first page and nextCursor null ends the list. + security: + - webSession: [] + - appOAuth: [organizations:read] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/Limit' + - $ref: './common.yaml#/components/parameters/Cursor' + responses: + '200': + description: One page of invitations. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationInvitationPage' + examples: + lastPage: + $ref: '#/components/examples/OrganizationInvitationPageLast' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' post: tags: [Organizations] - operationId: addOrganizationMember - summary: Add a person to an organization + operationId: createOrganizationInvitation + summary: Invite somebody to an organization description: >- - Make somebody who already has an account here a member of the - organization, by their email address, with a role. Only an owner or - an admin of this organization can. A repeated request with the same - Idempotency-Key and body returns the first result. + Invite the person with this email address to join the organization + with a role. They need no account yet: the invitation waits for + whoever signs in with that address, and they see it in OpenBot then. + Where OpenBot can send email, it also emails them; delivery says + which happened, so the inviter knows whether to pass the link on + themselves. The invitation lasts seven days. Inviting an address + again after its invitation expired or was declined starts a new one. + Only an owner or an admin of this organization can. A repeated + request with the same Idempotency-Key and body returns the first + result. security: - webSession: [] - appOAuth: [organizations:write] @@ -165,7 +396,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/AddOrganizationMemberRequest' + $ref: '#/components/schemas/CreateOrganizationInvitationRequest' examples: member: value: @@ -173,45 +404,260 @@ paths: role: member responses: '201': - description: The person is now a member. + description: The invitation was made. headers: Cache-Control: $ref: './common.yaml#/components/headers/PrivateNoStore' Location: - description: The organization's members. + description: The organization's invitations. schema: type: string - example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/members + example: /api/v2/organizations/Jq3xT9mLw2Vb8RnC5sYd0fKe/invitations content: application/json: schema: - $ref: '#/components/schemas/OrganizationMemberResponse' + $ref: '#/components/schemas/OrganizationInvitationResponse' examples: - added: - $ref: '#/components/examples/AddedOrganizationMember' + invited: + $ref: '#/components/examples/CreatedOrganizationInvitation' '400': - $ref: '#/components/responses/InvalidOrganizationMember' + $ref: '#/components/responses/InvalidOrganizationInvitation' '401': $ref: './common.yaml#/components/responses/Unauthenticated' '403': $ref: './common.yaml#/components/responses/AdminOnly' '404': - $ref: '#/components/responses/OrganizationOrPersonNotFound' + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/OrganizationInvitationConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/invitations/{invitationId}: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/InvitationId' + delete: + tags: [Organizations] + operationId: cancelOrganizationInvitation + summary: Cancel an invitation + description: >- + Take back an invitation the organization sent, whatever state it is + in. It leaves the organization's list and the invited person's. Only + an owner or an admin of this organization can. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '204': + description: The invitation is canceled. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/OrganizationOrInvitationNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/people/me/invitations: + get: + tags: [Organizations] + operationId: listInvitations + summary: List the caller's invitations + description: >- + Return one page of the invitations sent to the caller's email address + that they have not answered, the newest first, each with the + organization and who invited them. One that ran out of time is listed + as expired until it is canceled or replaced. A missing cursor starts + at the first page and nextCursor null ends the list. + security: + - webSession: [] + - appOAuth: [organizations:read] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/Limit' + - $ref: './common.yaml#/components/parameters/Cursor' + responses: + '200': + description: One page of invitations. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/InvitationPage' + examples: + lastPage: + $ref: '#/components/examples/InvitationPageLast' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/people/me/invitations/{invitationId}: + parameters: + - $ref: '#/components/parameters/InvitationId' + get: + tags: [Organizations] + operationId: getInvitation + summary: Read one of the caller's invitations + description: >- + Return an invitation sent to the caller's email address, in whatever + state it is in, so the page a link opens can say what happened to it. + An invitation sent to another address answers as one that does not + exist. + security: + - webSession: [] + - appOAuth: [organizations:read] + - apiKey: [] + responses: + '200': + description: The invitation. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/InvitationResponse' + examples: + waiting: + $ref: '#/components/examples/WaitingInvitation' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/InvitationNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/people/me/invitations/{invitationId}/accept: + parameters: + - $ref: '#/components/parameters/InvitationId' + post: + tags: [Organizations] + operationId: acceptInvitation + summary: Accept an invitation + description: >- + Join the organization the invitation is for, with the role it offers. + The caller's session keeps working where it was; switch to the new + organization to work in it. An invitation that expired, was canceled + or was already answered is refused in words. A repeated request with + the same Idempotency-Key returns the first result. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '200': + description: The caller is now a member of the organization. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationResponse' + examples: + joined: + $ref: '#/components/examples/JoinedOrganization' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/InvitationNotFound' '409': - $ref: '#/components/responses/OrganizationMemberConflict' + $ref: '#/components/responses/InvitationNotWaiting' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/people/me/invitations/{invitationId}/decline: + parameters: + - $ref: '#/components/parameters/InvitationId' + post: + tags: [Organizations] + operationId: declineInvitation + summary: Decline an invitation + description: >- + Turn the invitation down. It leaves the caller's list, and the + organization sees that it was declined. A repeated request with the + same Idempotency-Key returns the first result. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '204': + description: The invitation is declined. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/InvitationNotFound' + '409': + $ref: '#/components/responses/InvitationNotWaiting' '500': $ref: './common.yaml#/components/responses/ServerError' default: $ref: './common.yaml#/components/responses/UnexpectedError' components: + parameters: + InvitationId: + name: invitationId + in: path + required: true + description: The invitation's id. Opaque. + schema: + type: string + minLength: 1 + maxLength: 128 + pattern: ^[A-Za-z0-9_-]+$ schemas: Organization: type: object description: >- One organization, as one of its members sees it. role and active are the server's verdicts about the caller. - required: [id, slug, name, role, active] + required: [id, slug, name, role, active, personal] properties: + personal: + type: boolean + description: >- + Whether this is the caller's own organization: the one OpenBot + made for them when they first signed in. id: type: string description: The organization's id. Opaque. @@ -226,8 +672,10 @@ components: active: type: boolean description: >- - Whether the caller's session is working in this one. Always false - for a request with no session. + Whether the caller is working in this one: the organization their + session works in, or for an app's token the one its + OpenBot-Organization header names, else the caller's own. Always + false for a request made with an API key. OrganizationPage: type: object required: [organizations, canCreate, nextCursor] @@ -240,9 +688,9 @@ components: canCreate: type: boolean description: >- - Whether the caller may create an organization: the server's - verdict, true for the deployment's admins and for anybody signed - in when the deployment lets them. The same on every page. + Whether the caller may create another organization: the server's + verdict, true for anybody signed in where OpenBot keeps more than + one organization. The same on every page. nextCursor: type: [string, 'null'] maxLength: 4096 @@ -278,8 +726,24 @@ components: OrganizationMember: type: object description: One member of an organization. - required: [id, email, name, image, role, joinedAt] + required: [id, email, name, image, role, joinedAt, removable, assignableRoles] properties: + removable: + type: boolean + description: >- + Whether this membership can end: an admin can remove them and + they can leave. The server's verdict. False for the + organization's last owner, who stays in it, for the owner of + their own organization, and for somebody this OpenBot's settings + keep as an admin of the organization. + assignableRoles: + type: array + description: >- + The roles the caller may give this member, their current one left + out. The server's verdict. Empty when the caller may not change + this member's role. + items: + $ref: './common.yaml#/components/schemas/PersonRole' id: type: string description: The person's id. @@ -320,7 +784,97 @@ components: properties: member: $ref: '#/components/schemas/OrganizationMember' - AddOrganizationMemberRequest: + UpdateOrganizationMemberRequest: + type: object + additionalProperties: false + required: [role] + properties: + role: + $ref: './common.yaml#/components/schemas/PersonRole' + UpdateOrganizationRequest: + type: object + additionalProperties: false + required: [name] + properties: + name: + type: string + minLength: 1 + maxLength: 100 + pattern: ^[^\x00]*\S[^\x00]*$ + description: What people call it. + InvitationSender: + type: object + description: Who sent an invitation. + required: [name, email] + properties: + name: + type: [string, 'null'] + description: What OpenBot calls them. Null until they choose. + email: + type: string + description: Their address. + OrganizationInvitation: + type: object + description: >- + An invitation an organization sent, as its admins see it. status is + the server's verdict. + required: [id, email, role, status, invitedBy, createdAt, expiresAt] + properties: + id: + type: string + description: The invitation's id. Opaque. + email: + type: string + description: The address it was sent to. + role: + $ref: './common.yaml#/components/schemas/AssignableRole' + status: + type: string + enum: [pending, expired, declined] + description: >- + pending while it waits for an answer, expired once its seven days + ran out, declined when the person turned it down. + invitedBy: + $ref: '#/components/schemas/InvitationSender' + createdAt: + type: string + format: date-time + description: When it was sent. + expiresAt: + type: string + format: date-time + description: When it stops being accepted. + OrganizationInvitationPage: + type: object + required: [invitations, nextCursor] + properties: + invitations: + type: array + description: The newest first. + items: + $ref: '#/components/schemas/OrganizationInvitation' + nextCursor: + type: [string, 'null'] + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: >- + Pass as cursor for the next page. Null ends the list. Written in + URL-safe base64, the only form the cursor parameter accepts. + OrganizationInvitationResponse: + type: object + required: [invitation, delivery] + properties: + invitation: + $ref: '#/components/schemas/OrganizationInvitation' + delivery: + type: string + enum: [emailed, link] + description: >- + How the person hears of it. emailed when OpenBot sent them an + email. link when it could not or is not set up to, so the inviter + passes the invitation's link on themselves. Either way the person + sees the invitation in OpenBot when they sign in. + CreateOrganizationInvitationRequest: type: object additionalProperties: false required: [email, role] @@ -330,9 +884,74 @@ components: minLength: 3 maxLength: 320 pattern: ^[^\s\x00]+@[^\s\x00]+$ - description: The address of somebody who already has an account here. + description: The address of the person to invite. + role: + $ref: './common.yaml#/components/schemas/AssignableRole' + Invitation: + type: object + description: >- + An invitation as the person it was sent to sees it. status is the + server's verdict. + required: [id, organization, role, status, invitedBy, createdAt, expiresAt] + properties: + id: + type: string + description: The invitation's id. Opaque. + organization: + type: object + description: The organization it is an invitation to. + required: [id, slug, name] + properties: + id: + type: string + description: The organization's id. Opaque. + slug: + type: string + description: Its short name. + name: + type: string + description: What people call it. role: $ref: './common.yaml#/components/schemas/AssignableRole' + status: + type: string + enum: [pending, expired, accepted, declined, canceled] + description: >- + pending while it can still be answered. expired once its seven + days ran out, accepted or declined once the person answered, + canceled when the organization took it back. + invitedBy: + $ref: '#/components/schemas/InvitationSender' + createdAt: + type: string + format: date-time + description: When it was sent. + expiresAt: + type: string + format: date-time + description: When it stops being accepted. + InvitationPage: + type: object + required: [invitations, nextCursor] + properties: + invitations: + type: array + description: The newest first. + items: + $ref: '#/components/schemas/Invitation' + nextCursor: + type: [string, 'null'] + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: >- + Pass as cursor for the next page. Null ends the list. Written in + URL-safe base64, the only form the cursor parameter accepts. + InvitationResponse: + type: object + required: [invitation] + properties: + invitation: + $ref: '#/components/schemas/Invitation' responses: InvalidOrganization: description: The name or the slug is missing or malformed, or the Idempotency-Key is. @@ -403,28 +1022,31 @@ components: retryable: true requestId: req_example traceId: trace_example - InvalidOrganizationMember: - description: The address or the role is missing or malformed, or the Idempotency-Key is. + OwnerStays: + description: >- + The person stays in the organization: they own it, or this OpenBot's + settings keep them as an admin of it. The members list says who, as + removable. content: application/problem+json: schema: $ref: './common.yaml#/components/schemas/Problem' examples: - role: + owner: value: - type: https://open.bot/errors/validation-error - title: Request validation failed. - status: 400 - detail: A role of admin or member is required. - code: VALIDATION_ERROR - category: validation + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: They own this organization, so they stay a member of it. + code: CONFLICT + category: conflict retryable: false requestId: req_example traceId: trace_example - OrganizationOrPersonNotFound: + OrganizationOrInvitationNotFound: description: >- The organization does not exist or is not visible to the caller, or - nobody here has that address. + it has no such invitation. content: application/problem+json: schema: @@ -441,21 +1063,89 @@ components: retryable: false requestId: req_example traceId: trace_example - person: + invitation: value: - type: https://open.bot/errors/person-not-found - title: Person not found. + type: https://open.bot/errors/invitation-not-found + title: Invitation not found. status: 404 - detail: Nobody here has that address. They need to sign in to OpenBot once first. - code: PERSON_NOT_FOUND + detail: Couldn't find that invitation. + code: INVITATION_NOT_FOUND category: not_found retryable: false requestId: req_example traceId: trace_example - OrganizationMemberConflict: + InvitationNotFound: + description: >- + There is no such invitation, or it was sent to another address. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + invitation: + value: + type: https://open.bot/errors/invitation-not-found + title: Invitation not found. + status: 404 + detail: Couldn't find that invitation. Check that you're signed in with the address it was sent to. + code: INVITATION_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + InvitationNotWaiting: + description: >- + The invitation expired, was canceled or was already answered. Or the + Idempotency-Key was used for a different request. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + expired: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: This invitation has expired. Ask whoever invited you to send a new one. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + reused: + value: + type: https://open.bot/errors/idempotency-key-conflict + title: That Idempotency-Key was used for a different request. + status: 409 + detail: That Idempotency-Key was used for a different request. + code: IDEMPOTENCY_KEY_CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + InvalidOrganizationInvitation: + description: The address or the role is missing or malformed, or the Idempotency-Key is. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + role: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A role of admin or member is required. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + OrganizationInvitationConflict: description: >- - They are already a member. Or the Idempotency-Key was used for a - different request. + They are already a member, or already have an invitation waiting. Or + the Idempotency-Key was used for a different request. content: application/problem+json: schema: @@ -472,6 +1162,17 @@ components: retryable: false requestId: req_example traceId: trace_example + invited: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: They already have an invitation waiting. Cancel it to send a new one. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example reused: value: type: https://open.bot/errors/idempotency-key-conflict @@ -485,19 +1186,21 @@ components: traceId: trace_example examples: OrganizationPageLast: - summary: Somebody in two organizations, working in the first. + summary: Somebody in their own organization and one they created, working in their own. value: organizations: - - id: default - slug: default - name: Acme - role: admin + - id: Wm4pZ7tKc1Xb9RnQ2sYd6hLe + slug: dana + name: Dana's organization + role: owner active: true + personal: true - id: Jq3xT9mLw2Vb8RnC5sYd0fKe slug: acme-research name: Acme Research role: owner active: false + personal: false canCreate: true nextCursor: null CreatedOrganization: @@ -509,6 +1212,7 @@ components: name: Acme Research role: owner active: false + personal: false OrganizationMemberPageLast: summary: An organization's members, on one page. value: @@ -519,20 +1223,116 @@ components: image: null role: owner joinedAt: '2026-11-14T09:12:40.000Z' + removable: false + assignableRoles: [] - id: 2fn8w1c6y4tq7h0mbe3s email: sam.ortiz@acme.com name: Sam Ortiz image: null role: member joinedAt: '2026-11-14T09:20:05.000Z' + removable: true + assignableRoles: [owner, admin] nextCursor: null - AddedOrganizationMember: - summary: Somebody added as a member. + PromotedOrganizationMember: + summary: A member an owner has made an owner too. value: member: id: 2fn8w1c6y4tq7h0mbe3s email: sam.ortiz@acme.com name: Sam Ortiz image: null - role: member + role: owner joinedAt: '2026-11-14T09:20:05.000Z' + removable: true + assignableRoles: [admin, member] + RenamedOrganization: + summary: An organization with its new name. + value: + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research Lab + role: owner + active: true + personal: false + JoinedOrganization: + summary: The organization somebody joined by accepting an invitation. + value: + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research + role: member + active: false + personal: false + OrganizationInvitationPageLast: + summary: One invitation waiting and one that expired. + value: + invitations: + - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + email: sam.ortiz@acme.com + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + - id: 0c2d7a53-1f4e-4f0a-8a57-3d1b2c9e7f42 + email: lee.park@acme.com + role: admin + status: expired + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-01T09:20:05.000Z' + expiresAt: '2026-11-08T09:20:05.000Z' + nextCursor: null + CreatedOrganizationInvitation: + summary: An invitation OpenBot could not email, so the inviter passes the link on. + value: + invitation: + id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + email: sam.ortiz@acme.com + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + delivery: link + InvitationPageLast: + summary: One invitation waiting for the caller. + value: + invitations: + - id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' + nextCursor: null + WaitingInvitation: + summary: An invitation the caller can still answer. + value: + invitation: + id: 5b0f6f0e-6f0b-4c0e-9d57-0d6f3a5f9a11 + organization: + id: Jq3xT9mLw2Vb8RnC5sYd0fKe + slug: acme-research + name: Acme Research + role: member + status: pending + invitedBy: + name: Dana Whitfield + email: dana.whitfield@acme.com + createdAt: '2026-11-15T09:20:05.000Z' + expiresAt: '2026-11-22T09:20:05.000Z' diff --git a/api/openapi/passwords-and-recorder.yaml b/api/openapi/passwords-and-recorder.yaml index c4e866a491..8d90ac74d5 100644 --- a/api/openapi/passwords-and-recorder.yaml +++ b/api/openapi/passwords-and-recorder.yaml @@ -125,7 +125,10 @@ paths: it has got to, the last thing that happened, and the usernames of the person's saved logins for that site while the password manager is on. Never a credential. Only the person it was opened - for may read it; anybody else's is not found. + for may read it; anybody else's is not found. A request belongs to + the organization the Bot asked in, and is not found in any other, so + the link a Bot hands the person (/sign-in/{signInRequestId}) opens + only while they are working in that organization. security: - webSession: [] - appOAuth: [sign-in-requests:read] @@ -822,7 +825,9 @@ paths: description: >- End the connection the request is signed with: the Recorder's own Disconnect. Signed with the Recorder's connection token and - nothing else. + nothing else. organizationId is `default` or the connection's own + organization, and either way the call acts in the connection's + organization. security: - recorderConnection: [] parameters: @@ -856,7 +861,9 @@ paths: description: >- Return the person this Recorder's connection acts as, and the connection's id. Signed with the Recorder's connection token and - nothing else. A connection that has ended is refused as signed + nothing else. organizationId is `default` or the connection's own + organization, and either way the answer is for the connection's + organization. A connection that has ended is refused as signed out, with why. x-openbot-singleton: true security: @@ -897,6 +904,8 @@ paths: Return whether the recordings this Recorder's person makes land in their own Learning space, which is made on first need. Signed with the Recorder's connection token and nothing else. + organizationId is `default` or the connection's own organization, + and either way the answer is for the connection's organization. x-openbot-singleton: true security: - recorderConnection: [] @@ -938,7 +947,9 @@ paths: a recording runs, so OpenBot can show a recording wherever the person made it. Kept against the connection in place of the last report, and never audited: it is a heartbeat. Signed with the - Recorder's connection token and nothing else. + Recorder's connection token and nothing else. organizationId is + `default` or the connection's own organization, and either way the + report is kept in the connection's organization. security: - recorderConnection: [] parameters: diff --git a/api/openapi/schedules.yaml b/api/openapi/schedules.yaml index 189ee27bbe..fbb7e436b3 100644 --- a/api/openapi/schedules.yaml +++ b/api/openapi/schedules.yaml @@ -701,10 +701,11 @@ paths: - Check-ins operationId: getCheckInUsage summary: Read how check-ins are going - description: "Return, per Bot, over the last 7 or 30 days: how its check-ins - ended, what they raised, what people did with it and how many notices - carried it, with the daily limit in force. Counts only: no item's title, - source or person. Only an administrator may read it." + description: "Return, per Bot in the organization, over the last 7 or 30 + days: how its check-ins ended, what they raised, what people did with + it and how many notices carried it, with the organization's daily limit + in force. Counts only: no item's title, source or person. Only an + administrator of the organization may read it." x-openbot-singleton: true security: - webSession: [] diff --git a/api/openapi/skills.yaml b/api/openapi/skills.yaml index e95214d9a9..d1c9ee97c7 100644 --- a/api/openapi/skills.yaml +++ b/api/openapi/skills.yaml @@ -11,8 +11,12 @@ paths: operationId: listSkills summary: List skills description: >- - Return one page of the skills the caller can see: the organization's - and their own. An admin sees everybody's. Ordered by title, then + Return one page of the skills the caller can see: their own, the + ones granted to a team they are in, and the organization's that are + granted to no team. An organization's skill granted to teams is + listed only to those teams' people. An admin of the organization + sees every skill. + Another organization's skills are never listed. Ordered by title, then slug. A missing cursor starts at the first page and nextCursor null ends the list. security: @@ -56,8 +60,8 @@ paths: operationId: getSkill summary: Read a skill description: >- - Return one skill the caller can see: the organization's or their own. - An admin can read anybody's. Somebody else's skill is not found. + Return one skill the caller can see, as the list shows them. An admin + can read any. One the caller can't see is not found. security: - webSession: [] - appOAuth: [skills:read] @@ -177,6 +181,99 @@ paths: $ref: './common.yaml#/components/responses/ServerError' default: $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/skills/{skillId}/team-grants: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/SkillId' + get: + tags: [Skills] + operationId: getSkillTeamGrants + summary: Read the teams the skill is granted to + description: >- + Return the teams the skill is granted to, by id. A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. Only an admin + of the organization may read them. + x-openbot-singleton: true + security: + - webSession: [] + - appOAuth: [skills:read] + - apiKey: [] + responses: + '200': + description: The teams the skill is granted to. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/SkillTeamGrants' + examples: + granted: + $ref: '#/components/examples/SkillTeamGrantsExample' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/SkillOrTeamNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + put: + tags: [Skills] + operationId: replaceSkillTeamGrants + summary: Grant a skill to teams + description: >- + Grant the skill to exactly these teams of the organization, taking it + from any team left out. An empty list takes it from every team. + A person in one of those teams, or in a team beneath one, may put the skill on a Bot they own, and the Bot is offered it only while they stay in such a team. A team of another organization is not found. Only an admin + of the organization may do this. Recorded on the audit trail. + security: + - webSession: [] + - appOAuth: [skills:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SkillTeamGrantsInput' + examples: + oneTeam: + value: + teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze] + responses: + '200': + description: The teams the skill is now granted to. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/SkillTeamGrants' + examples: + granted: + $ref: '#/components/examples/SkillTeamGrantsExample' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: '#/components/responses/SkillOrTeamNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' components: parameters: SkillId: @@ -199,7 +296,7 @@ components: description: >- A named instruction a person runs with / in a conversation, on a Bot that offers it. - required: [slug, title, summary, instructions, tools, ownerId, botIds] + required: [slug, title, summary, instructions, tools, ownerId, botIds, usableOnYourBots] properties: slug: type: string @@ -229,6 +326,12 @@ components: description: The Bots that offer it, by id. items: type: string + usableOnYourBots: + type: boolean + description: >- + Whether the caller may put it on a Bot they own: it is their own, + or it is granted to a team they are in. A Bot's Skills page offers + these. SkillInput: type: object additionalProperties: false @@ -263,6 +366,30 @@ components: description: >- Make a new skill the organization's. Only an admin may. It applies when the skill is made: rewriting one keeps whose it is. + SkillTeamGrants: + type: object + description: The teams the skill is granted to. + required: [teams] + properties: + teams: + type: array + description: Each team's id, in order. + items: + type: string + SkillTeamGrantsInput: + type: object + additionalProperties: false + required: [teams] + properties: + teams: + type: array + maxItems: 100 + description: The id of each team of this organization to grant it to. + items: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ SkillPage: type: object required: [skills, nextCursor] @@ -282,8 +409,8 @@ components: responses: SkillNotFound: description: >- - No skill has that slug, it is somebody else's and the caller isn't an - admin, or the organization does not exist. + No skill has that slug, the caller isn't an admin and can't see it, + or the organization does not exist. content: application/problem+json: schema: @@ -300,6 +427,37 @@ components: retryable: false requestId: req_example traceId: trace_example + SkillOrTeamNotFound: + description: >- + There is no skill by that slug, a team named is not one of this + organization's, or the organization does not exist. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + skill: + value: + type: https://open.bot/errors/skill-not-found + title: Skill not found. + status: 404 + detail: There is no skill called standup. + code: SKILL_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example InvalidSkill: description: >- A field is missing, blank once trimmed or holds text that can't be @@ -374,6 +532,7 @@ components: tools: [google-calendar/list_events] ownerId: user_3f1c9a botIds: [general-assistant] + usableOnYourBots: true - slug: weekly-report title: Weekly report summary: Sum up the week's work for the team. @@ -381,7 +540,12 @@ components: tools: [] ownerId: null botIds: [general-assistant, research-assistant] + usableOnYourBots: false nextCursor: null + SkillTeamGrantsExample: + summary: Granted to one team. + value: + teams: [Tm4Qx8LpV2nWc7RbY1sKd0Ze] SkillExample: summary: A person's own skill, offered by one Bot. value: @@ -392,3 +556,4 @@ components: tools: [google-calendar/list_events] ownerId: user_3f1c9a botIds: [general-assistant] + usableOnYourBots: true diff --git a/api/openapi/teams.yaml b/api/openapi/teams.yaml new file mode 100644 index 0000000000..7e579c0511 --- /dev/null +++ b/api/openapi/teams.yaml @@ -0,0 +1,860 @@ +# Teams: the named groups of people inside one organization, and each team's members. +# +# One area of OpenBot's REST API. `bun run api:bundle` joins every area with common.yaml into +# api/openapi.yaml, the file every client and check reads. See api/README.md. +paths: + /api/v2/organizations/{organizationId}/teams: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + get: + tags: [Teams] + operationId: listTeams + summary: List an organization's teams + description: >- + Return one page of the organization's teams, in the order they were + created. Any member of the organization can read it. Each team says + the caller's own role in it and whether the caller may manage it. A + missing cursor starts at the first page and nextCursor null ends the + list. + security: + - webSession: [] + - appOAuth: [organizations:read] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/Limit' + - $ref: './common.yaml#/components/parameters/Cursor' + responses: + '200': + description: One page of teams. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamPage' + examples: + lastPage: + $ref: '#/components/examples/TeamPageLast' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + post: + tags: [Teams] + operationId: createTeam + summary: Create a team + description: >- + Create a team in the organization. Only an owner or an admin of the + organization can. A team's name is unique in its organization, + whatever its case. A team may sit under a parent team, and then its + members can use everything granted to the parent as well. A repeated + request with the same Idempotency-Key and body returns the first + result. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTeamRequest' + examples: + named: + value: + name: Sales + description: Everybody who sells. + responses: + '201': + description: The team was created. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + Location: + description: The new team. + schema: + type: string + example: /api/v2/organizations/default/teams/Tm4Qx8LpV2nWc7RbY1sKd0Ze + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + examples: + created: + $ref: '#/components/examples/CreatedTeam' + '400': + $ref: '#/components/responses/InvalidTeam' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/AdminOnly' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '409': + $ref: '#/components/responses/TeamConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams/{teamId}: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TeamId' + get: + tags: [Teams] + operationId: getTeam + summary: Read one team + description: >- + Return one of the organization's teams. Any member of the + organization can read it. A team of another organization is not + found. + security: + - webSession: [] + - appOAuth: [organizations:read] + - apiKey: [] + responses: + '200': + description: The team. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + examples: + team: + $ref: '#/components/examples/CreatedTeam' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + patch: + tags: [Teams] + operationId: updateTeam + summary: Change a team + description: >- + Change a team's name, its description or its parent team; a field + that is absent stays as it is, and a null parent takes the team out + from under its parent. An owner or an admin of the organization can, + and so can one of the team's maintainers, except that only an owner + or an admin changes its parent. A team that comes from the company's + directory keeps the directory's name. A team can't be put under + itself or under a team beneath it. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTeamRequest' + examples: + renamed: + value: + name: Sales EMEA + responses: + '200': + description: The team as it now is. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamResponse' + examples: + changed: + $ref: '#/components/examples/CreatedTeam' + '400': + $ref: '#/components/responses/InvalidTeam' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '409': + $ref: '#/components/responses/TeamConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + delete: + tags: [Teams] + operationId: deleteTeam + summary: Delete a team + description: >- + Delete a team. Its members stay in the organization and lose what + was granted to the team, at once. Teams under it move up to its own + parent. Only an owner or an admin of the organization can. A team + that comes from the company's directory is removed there, not here. + Deleting a team that is not there changes nothing. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '204': + description: The team is gone. + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: './common.yaml#/components/responses/OrganizationNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams/{teamId}/members: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TeamId' + get: + tags: [Teams] + operationId: listTeamMembers + summary: List a team's members + description: >- + Return one page of the people in a team, in the order they joined + it. Any member of the organization can read it. People who are only + in a team beneath this one are not listed. A missing cursor starts at + the first page and nextCursor null ends the list. + security: + - webSession: [] + - appOAuth: [organizations:read] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/Limit' + - $ref: './common.yaml#/components/parameters/Cursor' + responses: + '200': + description: One page of the team's members. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamMemberPage' + examples: + lastPage: + $ref: '#/components/examples/TeamMemberPageLast' + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: './common.yaml#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + /api/v2/organizations/{organizationId}/teams/{teamId}/members/{memberId}: + parameters: + - $ref: './common.yaml#/components/parameters/OrganizationId' + - $ref: '#/components/parameters/TeamId' + - $ref: '#/components/parameters/TeamMemberId' + put: + tags: [Teams] + operationId: putTeamMember + summary: Add a person to a team, or change their role in it + description: >- + Put a member of the organization in the team with a role, or change + the role of somebody already in it. What is granted to the team is + theirs from their next request. An owner or an admin of the + organization can, and so can one of the team's maintainers. A team + that comes from the company's directory takes its people from the + directory, so nobody is added to it here. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PutTeamMemberRequest' + examples: + member: + value: + role: member + responses: + '200': + description: The person as a member of the team. + headers: + Cache-Control: + $ref: './common.yaml#/components/headers/PrivateNoStore' + content: + application/json: + schema: + $ref: '#/components/schemas/TeamMemberResponse' + examples: + added: + $ref: '#/components/examples/AddedTeamMember' + '400': + $ref: '#/components/responses/InvalidTeamMember' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/TeamOrPersonNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' + delete: + tags: [Teams] + operationId: removeTeamMember + summary: Take a person out of a team + description: >- + Take a person out of the team. They stay in the organization and + lose what was granted to the team from their next request. An owner + or an admin of the organization can, so can one of the team's + maintainers, and anybody can take themselves out. A team that comes + from the company's directory takes its people from the directory, so + nobody is removed from it here. Removing somebody who is not in the + team changes nothing. + security: + - webSession: [] + - appOAuth: [organizations:write] + - apiKey: [] + parameters: + - $ref: './common.yaml#/components/parameters/IdempotencyKey' + responses: + '204': + description: They are not in the team. + '400': + $ref: './common.yaml#/components/responses/InvalidRequest' + '401': + $ref: './common.yaml#/components/responses/Unauthenticated' + '403': + $ref: '#/components/responses/TeamForbidden' + '404': + $ref: '#/components/responses/TeamNotFound' + '409': + $ref: './common.yaml#/components/responses/IdempotencyConflict' + '500': + $ref: './common.yaml#/components/responses/ServerError' + default: + $ref: './common.yaml#/components/responses/UnexpectedError' +components: + parameters: + TeamId: + name: teamId + in: path + required: true + description: The team's id. Opaque. + schema: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + example: Tm4Qx8LpV2nWc7RbY1sKd0Ze + TeamMemberId: + name: memberId + in: path + required: true + description: The person's id, or me for the caller. + schema: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + example: 2fn8w1c6y4tq7h0mbe3s + schemas: + TeamRole: + type: string + description: >- + A person's role in a team. A maintainer can rename the team and add + and remove its people; a member cannot. + enum: [maintainer, member] + TeamSource: + type: string + description: >- + Where a team comes from. openbot is a team made here. directory is a + group of the company's directory, kept in step with it: its name and + its people are the directory's and can't be changed here. + enum: [openbot, directory] + Team: + type: object + description: >- + One team of an organization, as one of the organization's members + sees it. role and canManage are the server's verdicts about the + caller. + required: + - id + - name + - description + - parentTeamId + - source + - memberCount + - role + - canManage + - canMove + - canDelete + - createdAt + properties: + id: + type: string + description: The team's id. Opaque. + name: + type: string + description: What people call it. Unique in its organization. + description: + type: [string, 'null'] + description: What the team is for, when somebody has said. + parentTeamId: + type: [string, 'null'] + description: >- + The team this one sits under, whose grants its members also have. + Null for a team under none. + source: + $ref: '#/components/schemas/TeamSource' + memberCount: + type: integer + minimum: 0 + description: How many people are in the team itself. + role: + oneOf: + - $ref: '#/components/schemas/TeamRole' + - type: 'null' + description: The caller's role in the team. Null when they are not in it. + canManage: + type: boolean + description: >- + Whether the caller may rename the team and add and remove its + people: the server's verdict. + canMove: + type: boolean + description: >- + Whether the caller may put the team under another team or take + it out from under one: the server's verdict, true for an owner + or an admin of the organization. + canDelete: + type: boolean + description: >- + Whether the caller may delete the team: the server's verdict, + true for an owner or an admin of the organization, and never for + a team that comes from the company's directory. + createdAt: + type: string + format: date-time + description: When the team was created. + TeamPage: + type: object + required: [teams, canCreate, nextCursor] + properties: + teams: + type: array + description: In the order they were created. + items: + $ref: '#/components/schemas/Team' + canCreate: + type: boolean + description: >- + Whether the caller may create a team here: the server's verdict. + The same on every page. + nextCursor: + type: [string, 'null'] + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: >- + Pass as cursor for the next page. Null ends the list. Written in + URL-safe base64, the only form the cursor parameter accepts. + TeamResponse: + type: object + required: [team] + properties: + team: + $ref: '#/components/schemas/Team' + CreateTeamRequest: + type: object + additionalProperties: false + required: [name] + properties: + name: + type: string + minLength: 1 + maxLength: 100 + pattern: ^[^\x00]*\S[^\x00]*$ + description: What people call it. + description: + type: string + maxLength: 500 + pattern: ^[^\x00]*$ + description: What the team is for. + parentTeamId: + type: string + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + description: A team of the same organization to put this one under. + UpdateTeamRequest: + type: object + additionalProperties: false + minProperties: 1 + properties: + name: + type: string + minLength: 1 + maxLength: 100 + pattern: ^[^\x00]*\S[^\x00]*$ + description: What people call it. + description: + type: [string, 'null'] + maxLength: 500 + pattern: ^[^\x00]*$ + description: What the team is for. Null clears it. + parentTeamId: + type: [string, 'null'] + minLength: 1 + maxLength: 200 + pattern: ^[A-Za-z0-9_-]+$ + description: >- + A team of the same organization to put this one under. Null takes + it out from under its parent. + TeamMember: + type: object + description: One person in a team. + required: [id, email, name, image, role, isCaller, joinedAt] + properties: + id: + type: string + description: The person's id. + email: + type: string + description: Their address. + name: + type: [string, 'null'] + description: What OpenBot calls them. Null until they choose. + image: + type: [string, 'null'] + description: Their picture's address, when they have one. + role: + $ref: '#/components/schemas/TeamRole' + isCaller: + type: boolean + description: Whether this person is the caller. + joinedAt: + type: string + format: date-time + description: When they joined the team. + TeamMemberPage: + type: object + required: [members, nextCursor] + properties: + members: + type: array + description: In the order they joined the team. + items: + $ref: '#/components/schemas/TeamMember' + nextCursor: + type: [string, 'null'] + maxLength: 4096 + pattern: ^[A-Za-z0-9_-]+$ + description: >- + Pass as cursor for the next page. Null ends the list. Written in + URL-safe base64, the only form the cursor parameter accepts. + TeamMemberResponse: + type: object + required: [member] + properties: + member: + $ref: '#/components/schemas/TeamMember' + PutTeamMemberRequest: + type: object + additionalProperties: false + required: [role] + properties: + role: + $ref: '#/components/schemas/TeamRole' + responses: + InvalidTeam: + description: >- + The name, the description or the parent is missing or malformed, the + parent is not a team that can hold this one, or the Idempotency-Key + is malformed. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + name: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A name of 1 to 100 characters is required. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + parent: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A team can't sit under itself or under a team beneath it. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + InvalidTeamMember: + description: The role is missing or malformed, or the Idempotency-Key is. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + role: + value: + type: https://open.bot/errors/validation-error + title: Request validation failed. + status: 400 + detail: A role of maintainer or member is required. + code: VALIDATION_ERROR + category: validation + retryable: false + requestId: req_example + traceId: trace_example + TeamForbidden: + description: >- + The caller may not change this team: they are neither an owner or an + admin of the organization nor one of the team's maintainers. Or the + team comes from the company's directory, which is where it is + changed. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + notAllowed: + value: + type: https://open.bot/errors/permission-denied + title: Permission denied. + status: 403 + detail: Only an admin of this organization or a maintainer of this team can change it. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + directory: + value: + type: https://open.bot/errors/permission-denied + title: Permission denied. + status: 403 + detail: This team comes from your company's directory. Change its people there. + code: PERMISSION_DENIED + category: permission + retryable: false + requestId: req_example + traceId: trace_example + TeamNotFound: + description: >- + The organization or the team does not exist or is not visible to the + caller. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + organization: + value: + type: https://open.bot/errors/organization-not-found + title: Organization not found. + status: 404 + detail: Couldn't find that organization. + code: ORGANIZATION_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + TeamOrPersonNotFound: + description: >- + The organization or the team does not exist or is not visible to the + caller, or the person is not a member of the organization. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + team: + value: + type: https://open.bot/errors/team-not-found + title: Team not found. + status: 404 + detail: Couldn't find that team. + code: TEAM_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + person: + value: + type: https://open.bot/errors/person-not-found + title: Person not found. + status: 404 + detail: They aren't a member of this organization. Add them to the organization first. + code: PERSON_NOT_FOUND + category: not_found + retryable: false + requestId: req_example + traceId: trace_example + TeamConflict: + description: >- + Another team of the organization has that name. Or the + Idempotency-Key was used for a different request. + content: + application/problem+json: + schema: + $ref: './common.yaml#/components/schemas/Problem' + examples: + nameTaken: + value: + type: https://open.bot/errors/conflict + title: The request conflicts with the current state. + status: 409 + detail: Another team here already has that name. Choose another. + code: CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + reused: + value: + type: https://open.bot/errors/idempotency-key-conflict + title: That Idempotency-Key was used for a different request. + status: 409 + detail: That Idempotency-Key was used for a different request. + code: IDEMPOTENCY_KEY_CONFLICT + category: conflict + retryable: false + requestId: req_example + traceId: trace_example + examples: + TeamPageLast: + summary: An organization's teams, on one page. + value: + teams: + - id: Tm4Qx8LpV2nWc7RbY1sKd0Ze + name: Sales + description: Everybody who sells. + parentTeamId: null + source: openbot + memberCount: 2 + role: maintainer + canManage: true + canMove: true + canDelete: true + createdAt: '2026-11-15T09:12:40.000Z' + - id: Fn2Wc6Yt4Qh7M0be3sKq8xLp + name: Finance + description: null + parentTeamId: null + source: directory + memberCount: 1 + role: null + canManage: false + canMove: true + canDelete: false + createdAt: '2026-11-15T09:20:05.000Z' + canCreate: true + nextCursor: null + CreatedTeam: + summary: A team made in OpenBot. + value: + team: + id: Tm4Qx8LpV2nWc7RbY1sKd0Ze + name: Sales + description: Everybody who sells. + parentTeamId: null + source: openbot + memberCount: 0 + role: null + canManage: true + canMove: true + canDelete: true + createdAt: '2026-11-15T09:12:40.000Z' + TeamMemberPageLast: + summary: A team's people, on one page. + value: + members: + - id: 8kq2m4x7p1rvz3a9c5d0 + email: dana.whitfield@acme.com + name: Dana Whitfield + image: null + role: maintainer + isCaller: true + joinedAt: '2026-11-15T09:13:02.000Z' + - id: 2fn8w1c6y4tq7h0mbe3s + email: sam.ortiz@acme.com + name: Sam Ortiz + image: null + role: member + isCaller: false + joinedAt: '2026-11-15T09:20:05.000Z' + nextCursor: null + AddedTeamMember: + summary: Somebody put in a team. + value: + member: + id: 2fn8w1c6y4tq7h0mbe3s + email: sam.ortiz@acme.com + name: Sam Ortiz + image: null + role: member + isCaller: false + joinedAt: '2026-11-15T09:20:05.000Z' diff --git a/api/redocly/rules.mjs b/api/redocly/rules.mjs index d815949eb4..e62ffc9834 100644 --- a/api/redocly/rules.mjs +++ b/api/redocly/rules.mjs @@ -14,11 +14,18 @@ import { parse } from "yaml"; const ORGANIZATION_PREFIX = "/api/v2/organizations/{organizationId}/"; /** - * The one address outside an organization: the organizations the caller is a member of, and - * creating one. A person has to be able to ask which organizations they are in before they can - * name one, so this cannot sit under an organization's address. + * The addresses outside an organization. The organizations the caller is a member of, and + * creating one: a person has to be able to ask which organizations they are in before they can + * name one. And the invitations sent to the caller: they answer one before they are a member of + * the organization it is for, so neither can sit under an organization's address. */ -const OUTSIDE_AN_ORGANIZATION = ["/api/v2/people/me/organizations"]; +const OUTSIDE_AN_ORGANIZATION = [ + "/api/v2/people/me/organizations", + "/api/v2/people/me/invitations", + "/api/v2/people/me/invitations/{invitationId}", + "/api/v2/people/me/invitations/{invitationId}/accept", + "/api/v2/people/me/invitations/{invitationId}/decline", +]; const WRITE_METHODS = ["post", "put", "patch", "delete"]; const METHODS = ["get", "head", "options", "trace", ...WRITE_METHODS]; const PROBLEM_JSON = "application/problem+json"; diff --git a/api/redocly/rules.test.ts b/api/redocly/rules.test.ts index 995e4f64f6..312fc2440e 100644 --- a/api/redocly/rules.test.ts +++ b/api/redocly/rules.test.ts @@ -1,4 +1,4 @@ -import { afterAll, expect, test } from "bun:test"; +import { afterAll, expect, setDefaultTimeout, test } from "bun:test"; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -12,6 +12,13 @@ import { parse, stringify } from "yaml"; * than letting the break through review. */ +/* + * Each lint is one run of the CLI over the whole spec: about 1 s on a laptop and 2.4 to 2.7 s on a CI + * runner, so a test that lints twice took 4.7 s there and one ran past Bun's 5 s default. Twenty + * seconds is four times the slowest seen. + */ +setDefaultTimeout(20_000); + const ROOT = join(import.meta.dir, "../.."); const SPEC = join(ROOT, "api/openapi.yaml"); const work = mkdtempSync(join(tmpdir(), "openbot-api-lint-")); @@ -86,10 +93,14 @@ test("each convention is enforced", () => { } }); -test("only the caller's own organizations sit outside an organization", () => { +test("only the caller's own organizations and invitations sit outside an organization", () => { const ORGANIZATIONS = "/api/v2/people/me/organizations"; - // The one address a person can ask before they can name an organization: allowed as committed. + // What a person can ask before they can name an organization, or before they are a member of + // the one an invitation is for: allowed as committed. expect(Object.keys(spec().paths)).toContain(ORGANIZATIONS); + expect(Object.keys(spec().paths)).toContain( + "/api/v2/people/me/invitations/{invitationId}/accept", + ); const broken = spec(); // Nothing beside it is: not another of the person's own resources, and not the address under it. broken.paths["/api/v2/people/me/bots"] = broken.paths[BOTS]; diff --git a/app/src/components/admin/admin-sections.ts b/app/src/components/admin/admin-sections.ts index aad35752f2..ba148f932b 100644 --- a/app/src/components/admin/admin-sections.ts +++ b/app/src/components/admin/admin-sections.ts @@ -7,6 +7,7 @@ import { IconLockAccess, IconShieldCheck, IconUsers, + IconUsersGroup, IconZoomQuestion, } from "@tabler/icons-react"; import type { LinkOptions } from "@tanstack/react-router"; @@ -28,7 +29,8 @@ const team = managePaths("team"); /** * Admin's pages, grouped by the thing a Bot has that each one sets for everybody, in the fixed order - * of `lib/primitives.ts`, then Vault, then the team itself. The sidebar and the overview both draw + * of `lib/primitives.ts`, then Vault, then the organization itself: its people and the teams they are + * in, what they may do, and how they sign in. The sidebar and the overview both draw * this list, so the two can never disagree about where a page is. * * Conversations has no group: it is where work happens, not something to set. Memory has none @@ -144,14 +146,14 @@ export const ADMIN_SECTIONS: readonly AdminSection[] = [ items: [ { title: team.credentialsLabel, - description: "Manage this deployment’s keys and tokens.", + description: "Manage this organization’s keys and tokens.", icon: VAULT.icon, linkOptions: team.credentials(), }, ], }, { - title: "Team", + title: "Organization", items: [ { title: "People", @@ -159,6 +161,13 @@ export const ADMIN_SECTIONS: readonly AdminSection[] = [ icon: IconUsers, linkOptions: { to: "/admin/people" }, }, + { + title: "Teams", + description: "Put people in teams, and give a team its own Bots.", + icon: IconUsersGroup, + /* Everybody's page, outside Admin: an admin does there what the server lets an admin do. */ + linkOptions: { to: "/teams" }, + }, { title: "Permissions", description: diff --git a/app/src/components/admin/controls/capabilities-section.tsx b/app/src/components/admin/controls/capabilities-section.tsx index dd9b0b2cdd..8853deaa72 100644 --- a/app/src/components/admin/controls/capabilities-section.tsx +++ b/app/src/components/admin/controls/capabilities-section.tsx @@ -4,7 +4,7 @@ import { IconToggleRight, IconUsersGroup, } from "@tabler/icons-react"; -import { useMutation } from "@tanstack/react-query"; +import { useMutation, useQuery } from "@tanstack/react-query"; import { Link } from "@tanstack/react-router"; import { useState } from "react"; import { PageRows } from "@/components/layout/page-shell"; @@ -37,13 +37,18 @@ import { import { Separator } from "@/components/ui/separator"; import { Switch } from "@/components/ui/switch"; import { setCapabilityMutationOptions } from "@/lib/enterprise/mutations"; -import type { EnterpriseOverview } from "@/lib/enterprise/queries"; +import type { + CapabilitySetting, + EnterpriseOverview, +} from "@/lib/enterprise/queries"; +import { MISSING_TEAM } from "@/lib/teams/names"; +import { teamListQueryOptions } from "@/lib/teams/queries"; import { queryClient } from "@/query-client"; import { ControlsSection } from "./controls-section"; /** * Admin, Permissions: what people may do, for the whole organization, with the row that opens the - * overrides for roles and directory groups. The page's only section, so it has no title of its own. + * overrides for roles and teams. The page's only section, so it has no title of its own. */ export function CapabilitiesSection() { const [overridesOpen, setOverridesOpen] = useState(false); @@ -54,6 +59,7 @@ export function CapabilitiesSection() { (count, capability) => count + Object.keys(capability.roles).length + + Object.keys(capability.teams).length + Object.keys(capability.groups).length, 0, ); @@ -73,7 +79,7 @@ export function CapabilitiesSection() { {effective ? capability.description - : "Off for everybody, unless a role or group turns it on."} + : "Off for everybody, unless a role or team turns it on."} @@ -104,7 +110,7 @@ export function CapabilitiesSection() { - Role and group overrides + Role and team overrides {overrideCount === 0 ? "None. Everybody gets the switches above" @@ -148,6 +154,38 @@ export function CapabilitiesSection() { type Tri = "inherit" | "on" | "off"; +/** Whose switches the dialog is showing: a role's, a team's, or a directory group's. */ +type Scope = { kind: "role" | "team" | "group"; id: string; label: string }; + +const scopeKey = (scope: Scope) => `${scope.kind}:${scope.id}`; + +/** What a scope set a permission to, or undefined where it sets nothing. */ +function storedAt( + capability: CapabilitySetting, + scope: Scope, +): boolean | undefined { + if (scope.kind === "role") + return capability.roles[scope.id as "admin" | "member"]; + return (scope.kind === "team" ? capability.teams : capability.groups)[ + scope.id + ]; +} + +const SCOPE_HINTS: Record = { + role: "A role's setting replaces the organization switch for everybody with that role.", + team: "A team can only add. Grant gives the people in it, and in the teams beneath it, the permission even when the organization has it off.", + group: + "This rule is for a directory group. You can remove it here. Make new rules for a team.", +}; + +/** + * The switches a role or a team sets over the organization's. + * + * A team is picked by name from the organization's teams, and its id is what a switch is saved + * under. Two kinds of rule are listed only because they are already there, so that nothing is lost + * and each can be removed: a directory group's, from before there were teams, and one for a team + * that has since been deleted. Neither can be given a new permission here. + */ function OverridesDialog({ data, open, @@ -158,38 +196,67 @@ function OverridesDialog({ onOpenChange: (open: boolean) => void; }) { const setCapability = useMutation(setCapabilityMutationOptions(queryClient)); - const scopes: { kind: "role" | "group"; id: string; label: string }[] = [ + const teams = useQuery({ ...teamListQueryOptions(), enabled: open }); + const known = teams.data?.teams ?? []; + const named = (level: "teams" | "groups") => [ + ...new Set( + data.capabilities.flatMap((capability) => Object.keys(capability[level])), + ), + ]; + const scopes: Scope[] = [ { kind: "role", id: "admin", label: "Admins" }, { kind: "role", id: "member", label: "Members" }, - ...data.groups.map((group) => ({ + ...known.map((team) => ({ + kind: "team" as const, + id: team.id, + label: `Team: ${team.name}`, + })), + // Only once the teams are known: until then a team with a rule can't be told from a deleted one. + ...(teams.data + ? named("teams") + .filter((id) => !known.some((team) => team.id === id)) + .map((id) => ({ kind: "team" as const, id, label: MISSING_TEAM })) + : []), + ...named("groups").map((group) => ({ kind: "group" as const, id: group, label: `Group: ${group}`, })), ]; - const [scopeIndex, setScopeIndex] = useState(0); - const scope = scopes[scopeIndex] ?? scopes[0]; + const [chosen, setChosen] = useState("role:admin"); + // A scope whose last rule was removed is no longer listed, so the dialog goes back to the first. + const scope = + scopes.find((candidate) => scopeKey(candidate) === chosen) ?? + (scopes[0] as Scope); + /* Whether the scope is listed for the rules it already has, and not to be given new ones. */ + const onlyItsRules = + scope.kind === "group" || + (scope.kind === "team" && !known.some((team) => team.id === scope.id)); return ( - Role and group overrides + Role and team overrides + {teams.error ? ( +

+ Couldn't load teams. Try again in a moment. +

+ ) : null}

- {scope?.kind === "group" - ? "A group can only add. Grant gives its members the capability even when the organization has it off." - : "A role's setting replaces the organization switch for everybody with that role."} + {scope.kind === "team" && onlyItsRules + ? "This team no longer exists. You can remove its rules here." + : SCOPE_HINTS[scope.kind]}

{scope ? data.capabilities.map((capability) => { - const stored = - scope.kind === "role" - ? capability.roles[scope.id as "admin" | "member"] - : capability.groups[scope.id]; + const stored = storedAt(capability, scope); + if (onlyItsRules && stored === undefined) return null; const value: Tri = stored === undefined ? "inherit" : stored ? "on" : "off"; return ( @@ -231,13 +301,22 @@ function OverridesDialog({ aria-label={`${capability.title} for ${scope.label}`} className="w-36" > - + {/* The words the list offers, where the trigger alone would show the value. */} + + {value === "inherit" + ? "Inherit" + : value === "off" + ? "Off" + : scope.kind === "role" + ? "On" + : "Grant"} + Inherit - {scope.kind === "group" ? "Grant" : "On"} + {scope.kind === "role" ? "On" : "Grant"} {scope.kind === "role" ? ( Off diff --git a/app/src/components/admin/controls/computer-sections.tsx b/app/src/components/admin/controls/computer-sections.tsx index 02028fe352..49e1d93aa1 100644 --- a/app/src/components/admin/controls/computer-sections.tsx +++ b/app/src/components/admin/controls/computer-sections.tsx @@ -2,9 +2,10 @@ import { IconChevronRight, IconDeviceDesktop, IconNetwork, + IconUsersGroup, IconWorld, } from "@tabler/icons-react"; -import { useMutation } from "@tanstack/react-query"; +import { useMutation, useQuery } from "@tanstack/react-query"; import { useId, useState } from "react"; import { PageRows } from "@/components/layout/page-shell"; import { Button } from "@/components/ui/button"; @@ -53,7 +54,10 @@ import type { EnterpriseOverview, NetworkMode, NetworkPolicy, + NetworkScopeKind, } from "@/lib/enterprise/queries"; +import { MISSING_TEAM, teamName } from "@/lib/teams/names"; +import { type TeamSummary, teamListQueryOptions } from "@/lib/teams/queries"; import { queryClient } from "@/query-client"; import { ControlsSection } from "./controls-section"; import { @@ -65,8 +69,8 @@ import { const MODE_NAMES: Record = { allow_all: "Allow all network access", - defaults_plus_allowlist: "Defaults plus team allowlist", - allowlist_only: "Team allowlist only", + defaults_plus_allowlist: "Defaults plus organization allowlist", + allowlist_only: "Organization allowlist only", }; /** @@ -151,112 +155,141 @@ export function InactiveComputersSection() { ); } -/** Admin, Computers: where Bot computers may connect, for the organization and per group. */ +/** Whose network policy a row or the dialog is about. An empty id with `team` is a new team policy. */ +type NetworkScope = { scopeKind: NetworkScopeKind; scopeId: string }; + +/** Admin, Computers: where Bot computers may connect, for the organization and per team. */ export function NetworkSection() { - const [networkScope, setNetworkScope] = useState< - { scopeKind: "organization" | "group"; scopeId: string } | undefined - >(); return ( - {({ data }) => { - const organizationPolicy = data.network.find( - (row) => row.scopeKind === "organization", - ); - const groupPolicies = data.network.filter( - (row) => row.scopeKind === "group", - ); - return ( - <> - - - setNetworkScope({ - scopeKind: "organization", - scopeId: "", - }) - } - type="button" - /> - } - size="sm" - > - - - - - Organization - - {summarizePolicy(organizationPolicy)} - - - - - - - {groupPolicies.map((policy) => ( -
- - - setNetworkScope({ - scopeKind: "group", - scopeId: policy.scopeId, - }) - } - type="button" - /> - } - size="sm" - > - - - - - Group: {policy.scopeId} - - {summarizePolicy(policy)} - - - - - - -
- ))} -
- {data.groups.length > 0 ? ( - - ) : null} - {networkScope ? ( - setNetworkScope(undefined)} - /> - ) : null} - - ); - }} + {({ data }) => }
); } +/** + * The organization's policy, then each team's and each directory group's. + * + * A new policy is made for a team, picked by name from the organization's teams, and is saved under + * the team's id. A directory group's policy, from before there were teams, stays listed as it was so + * it can be opened and removed, and so does one for a team that has since been deleted. + */ +function NetworkPolicies({ data }: { data: EnterpriseOverview }) { + const [networkScope, setNetworkScope] = useState(); + const teams = useQuery(teamListQueryOptions()); + const known = teams.data?.teams ?? []; + const organizationPolicy = data.network.find( + (row) => row.scopeKind === "organization", + ); + // A team's rows wait for the teams' names: a row is never titled with an id. + const scopedPolicies = data.network.filter( + (row) => + row.scopeKind === "group" || + (row.scopeKind === "team" && teams.data !== undefined), + ); + const titleOf = (policy: NetworkPolicy) => { + if (policy.scopeKind === "group") return `Group: ${policy.scopeId}`; + const name = teamName(known, policy.scopeId); + return name === MISSING_TEAM ? name : `Team: ${name}`; + }; + return ( + <> + + + setNetworkScope({ scopeKind: "organization", scopeId: "" }) + } + type="button" + /> + } + size="sm" + > + + + + + Organization + + {summarizePolicy(organizationPolicy)} + + + + + + + {scopedPolicies.map((policy) => ( +
+ + + setNetworkScope({ + scopeKind: policy.scopeKind, + scopeId: policy.scopeId, + }) + } + type="button" + /> + } + size="sm" + > + + {policy.scopeKind === "team" ? ( + + ) : ( + + )} + + + {/* A long team name wraps, and the row is a button, whose words center unless told. */} + {titleOf(policy)} + {summarizePolicy(policy)} + + + + + +
+ ))} +
+ {teams.error ? ( +

+ Couldn't load teams. Try again in a moment. +

+ ) : null} + {known.some( + (team) => + !data.network.some( + (row) => row.scopeKind === "team" && row.scopeId === team.id, + ), + ) ? ( + + ) : null} + {networkScope ? ( + setNetworkScope(undefined)} + teams={known} + /> + ) : null} + + ); +} + function SweepNow() { const sweep = useMutation(terminateInactiveComputersMutationOptions()); return ( @@ -286,17 +319,27 @@ function SweepNow() { function NetworkDialog({ data, initial, + teams, onClose, }: { data: EnterpriseOverview; - initial: { scopeKind: "organization" | "group"; scopeId: string }; + initial: NetworkScope; + /** The organization's teams, to pick a new policy's team from. */ + teams: TeamSummary[]; onClose: () => void; }) { const existing = data.network.find( (row) => row.scopeKind === initial.scopeKind && row.scopeId === initial.scopeId, ); - const [group, setGroup] = useState(initial.scopeId || data.groups[0] || ""); + /* A new team policy is for a team that has none yet: one that has is opened from its row. */ + const without = teams.filter( + (team) => + !data.network.some( + (row) => row.scopeKind === "team" && row.scopeId === team.id, + ), + ); + const [team, setTeam] = useState(initial.scopeId || without[0]?.id || ""); const [mode, setMode] = useState( existing?.mode ?? "defaults_plus_allowlist", ); @@ -305,7 +348,13 @@ function NetworkDialog({ const [written, setWritten] = useState(null); const save = useMutation(setNetworkPolicyMutationOptions(queryClient)); const remove = useMutation(removeNetworkPolicyMutationOptions(queryClient)); - const scopeId = initial.scopeKind === "group" ? group : ""; + const scoped = initial.scopeKind !== "organization"; + const scopeId = + initial.scopeKind === "team" + ? team + : initial.scopeKind === "group" + ? initial.scopeId + : ""; const formId = useId(); const entries = rulesFromText(rules); @@ -317,7 +366,7 @@ function NetworkDialog({ const broken = written !== null && !written.check.ok && !edited; /* * The policy as the dialog holds it, replayed once it differs from the one in force. Each part of - * the scope matters: a group's policy covers its members' Bots, and a locked organization policy + * the scope matters: a team's policy covers its people's Bots, and a locked organization policy * covers everybody's. */ const unchanged = @@ -326,7 +375,7 @@ function NetworkDialog({ existing.locked === locked && JSON.stringify(existing.rules) === JSON.stringify(entries); const candidate = - unchanged || broken || (initial.scopeKind === "group" && !scopeId) + unchanged || broken || (scoped && !scopeId) ? null : { scopeKind: initial.scopeKind, scopeId, mode, rules: entries, locked }; @@ -345,7 +394,9 @@ function NetworkDialog({ {initial.scopeKind === "organization" ? "Organization network policy" - : "Group network policy"} + : initial.scopeKind === "team" + ? "Team network policy" + : "Group network policy"} @@ -377,27 +428,39 @@ function NetworkDialog({ }} > - {initial.scopeKind === "group" && !initial.scopeId ? ( + {initial.scopeKind === "team" && !initial.scopeId ? ( - Group + Team + + The policy covers the Bots of the people in this team, and + in the teams beneath it. + + ) : scoped ? ( +

+ {initial.scopeKind === "group" + ? `This policy is for the directory group ${initial.scopeId}. You can change or remove it here. Make new policies for a team.` + : teams.some((one) => one.id === initial.scopeId) + ? `This policy covers the Bots of the people in ${teamName(teams, initial.scopeId)}, and in the teams beneath it.` + : "This team no longer exists, so its policy covers nobody. You can remove it."} +

) : null} @@ -449,7 +512,7 @@ function NetworkDialog({ {initial.scopeKind === "organization" ? (
+ + + ) : ( + <> + + + {offersStandingRule(request.action) ? ( + + + } + > + + + + decide("allow_conversation")} + > + Allow for this conversation + + decide("allow_always")} + > + Always allow here + + + + ) : null} + + )} + + ); +} + +/** Why an action waits on the person, in the words its policy gives, for a row's quiet line. */ +function requestReason(request: WaitingRequest): ReactNode { + const { policy } = request.action; + if (!policy) return null; + return ( + + {policy.behaviour === "hand_off" ? "Handed to you: " : ""} + {policy.reason} + + ); +} + +/** + * An action on the board: what it wants to do and where, with its answers on the right + * (`RequestAnswers`). Where it acts and what it would send are always on screen, whole: nobody + * allows something they were not shown. + */ +function RequestBoardRow({ request }: { request: WaitingRequest }) { + const words = approvalWords(request.action); const action = words.action.charAt(0).toUpperCase() + words.action.slice(1); return ( - - - - ) : ( - <> - - - {offersStandingRule(request.action) ? ( - - - } - > - - - - decide("allow_conversation")} - > - Allow for this conversation - - decide("allow_always")} - > - Always allow here - - - - ) : null} - - ) - } + actions={} detail={words.place} icon={} - meta={[ - request.action.policy ? ( - - {handOff ? "Handed to you: " : ""} - {request.action.policy.reason} - - ) : null, - decision.error ? ( - - {decision.error.message} - - ) : null, - ]} + meta={[requestReason(request)]} more={} open title={action} @@ -585,27 +618,127 @@ function RequestBoardRow({ request }: { request: WaitingRequest }) { ); } -/** The waiting questions and actions as rows, questions first, for a card that may hold more. */ -export function useWaitingRows(agentId: string | undefined) { +/** + * Answer, for a question a task waits on, from the board: the dialog with the whole question and + * the box to answer in, so the person answers without opening the thread. And Dismiss beside it. + */ +function QuestionAnswers({ question }: { question: WaitingQuestion }) { + const [answering, setAnswering] = useState(false); + const dismiss = useMutation( + dismissPersonQuestionMutationOptions(queryClient), + ); + return ( + <> + {dismiss.error ? ( + + {dismiss.error.message} + + ) : null} + + + + + ); +} + +/** + * What a task's row on the board answers with: the controls of the wait it stands for. A question or + * an action waiting in a task's own conversation is listed once, as the task's row, and that row + * carries its answers, so the person answers it there without opening the thread. + */ +export type HeldAnswer = { + actions: ReactNode; + meta: ReactNode[]; + more?: ReactNode; +}; + +/** + * For each task, the wait inside its conversation and how its row answers it, or undefined when + * nothing waits there. An action waiting is answered first, since the task cannot go on without it; + * then a question. + */ +export function useHeldAnswers(): (task: { + channelId: string; + threadId: string | null; +}) => HeldAnswer | undefined { + const waiting = useWaiting(undefined); + return (task) => { + const request = task.threadId + ? waiting.pending.find( + (pending) => pending.action.threadId === task.threadId, + ) + : undefined; + if (request) + return { + actions: , + meta: [requestReason(request)], + more: , + }; + const question = waiting.questions.find( + (asked) => + asked.channelId === task.channelId || + (task.threadId !== null && asked.threadId === task.threadId), + ); + if (question) + return { + actions: , + meta: question.why ? [{question.why}] : [], + }; + return undefined; + }; +} + +/** + * The waiting questions and actions as rows, questions first, for a card that may hold more. One + * held by a task (`heldByTask`) is left to that task's own row. + */ +export function useWaitingRows( + agentId: string | undefined, + heldByTask: (where: WaitingWhere) => boolean = () => false, +) { const waiting = useWaiting(agentId); const botName = useBotNames(); return { error: waiting.error, rows: [ - ...waiting.questions.map((question) => ( - - )), - ...waiting.pending.map((request) => ( - - )), + ...waiting.questions + .filter( + (question) => + !heldByTask({ + channelId: question.channelId, + threadId: question.threadId, + }), + ) + .map((question) => ( + + )), + ...waiting.pending + .filter((request) => !heldByTask({ threadId: request.action.threadId })) + .map((request) => ( + + )), ], }; } @@ -616,8 +749,15 @@ export function useWaitingRows(agentId: string | undefined) { * same requests the conversation draws inline, so a decision made in either place is the one * decision. */ -export function WaitingForYou({ agentId }: { agentId?: string }) { - const { error, rows } = useWaitingRows(agentId); +export function WaitingForYou({ + agentId, + heldByTask, +}: { + agentId?: string; + /** Leaves out what waits inside a task, for a list that shows the task itself. */ + heldByTask?: (where: WaitingWhere) => boolean; +}) { + const { error, rows } = useWaitingRows(agentId, heldByTask); return ( <> {error ? ( diff --git a/app/src/components/audit/audit-cells.tsx b/app/src/components/audit/audit-cells.tsx index 0ca2cd664b..1239c6471d 100644 --- a/app/src/components/audit/audit-cells.tsx +++ b/app/src/components/audit/audit-cells.tsx @@ -43,6 +43,12 @@ export type AuditEvent = { * ("Write a skill" for `skill-creator`). Not part of the stored row, so older rows read it too. */ subjectTitle?: string; + /** + * The address of the person the page found for the row's `actorUserId`, where the row records + * none of its own: a Bot's action, run on its person's authority. Not part of the stored row + * (components/manage/audit-page.tsx, `withPeopleNamed`). + */ + startedBy?: string; }; type NameFor = (botId: string) => string; @@ -144,11 +150,14 @@ export function WhoCell({ deployment, event, nameFor, + viewer, }: { /** What OpenBot itself is called here; see {@link startedByText}. */ deployment?: string; event: AuditEvent; nameFor: NameFor; + /** The signed-in person's email, read as "you"; see {@link startedByText}. */ + viewer?: string | null; }) { return ( <> @@ -160,6 +169,7 @@ export function WhoCell({ deployment={deployment} event={event} nameFor={nameFor} + viewer={viewer} />
@@ -455,15 +465,29 @@ function initiatorKindOf(event: AuditEvent): string | undefined { return ownChange ? "deployment" : event.initiatorKind; } +/** + * The person a row says started it, by the email the server records in `payload.by`, else the + * address the page found for the person whose authority it ran on (`startedBy`). The row carries no + * name, so the email is what every row can name. Undefined when the row names nobody. + */ +function personOf(event: AuditEvent): string | undefined { + const by = event.payload?.by; + if (typeof by === "string" && by.trim()) return by.trim(); + return event.startedBy?.trim() || undefined; +} + /** * Who started a row, as the row's Started by filter and its line under the Bot both say it. * `deployment` is what OpenBot itself is called on this screen: "this deployment" in Admin, and - * "OpenBot" in the personal edition's Activity, which is anybody's page. + * "OpenBot" in the personal edition's Activity, which is anybody's page. A person is named where + * the row or the page says who ({@link personOf}), "You" where that is `viewer` (the signed-in + * person's email), and is "A person" where nobody can. */ export function startedByText( event: AuditEvent, nameFor: NameFor, deployment = "this deployment", + viewer?: string | null, ): string { switch (initiatorKindOf(event)) { case "routine": @@ -478,8 +502,13 @@ export function startedByText( return "A goal"; case "deployment": return atStart(deployment); - default: - return "A person"; + default: { + const person = personOf(event); + if (!person) return "A person"; + return viewer && person.toLowerCase() === viewer.trim().toLowerCase() + ? "You" + : person; + } } } @@ -887,6 +916,7 @@ export function searchTextOf( event: AuditEvent, nameFor: NameFor, deployment?: string, + viewer?: string | null, ): string { return [ whatText(event), @@ -898,7 +928,9 @@ export function searchTextOf( subjectText(event, false), hostText(event), botText(event, nameFor), - startedByText(event, nameFor, deployment), + startedByText(event, nameFor, deployment, viewer), + // Who did it, by email, on any row that says so, whatever started it, "you" included. + personOf(event) ?? "", decisionText(event), decisionText(event, false), // Both ways a reason is said, as for the subject above. @@ -982,10 +1014,12 @@ export function StartedByCell({ deployment, event, nameFor, + viewer, }: { deployment?: string; event: AuditEvent; nameFor: NameFor; + viewer?: string | null; }) { // Anything that ran with nobody watching is the colour of a warning; a person or the deployment is not. const unattended = @@ -1001,19 +1035,20 @@ export function StartedByCell({ : "text-muted-foreground" } > - {startedByLine(startedByText(event, nameFor, deployment))} + {startedByLine(startedByText(event, nameFor, deployment, viewer))} ); } /** * Under the Bot's name, so it says what it is: "Started by a routine", "Handed on by Scout", - * "Started by OpenBot". Only a leading "A" or "This" is lowered; a name keeps its capitals. + * "Started by OpenBot", "Started by you". Only a leading "A" or "This", or "You" on its own, is + * lowered; a name keeps its capitals. */ export function startedByLine(text: string): string { return text.startsWith("Handed on") ? text - : `Started by ${text.replace(/^(A|This) /, (word) => word.toLowerCase())}`; + : `Started by ${text.replace(/^(?:(?:A|This) |You$)/, (word) => word.toLowerCase())}`; } export function DecisionCell({ diff --git a/app/src/components/audit/audit-table.tsx b/app/src/components/audit/audit-table.tsx index a320dbcd00..dd2209cceb 100644 --- a/app/src/components/audit/audit-table.tsx +++ b/app/src/components/audit/audit-table.tsx @@ -16,6 +16,7 @@ import { tableFeatures, useTable, } from "@tanstack/react-table"; +import { useQuery } from "@tanstack/react-query"; import type * as React from "react"; import { useMemo, useState } from "react"; import { PageEmpty } from "@/components/layout/page-shell"; @@ -37,6 +38,7 @@ import { TableRow, } from "@/components/ui/table"; import { type AuditOutcome, outcomeOf } from "@/lib/audit/outcome"; +import { currentUserQueryOptions } from "@/lib/auth/queries"; import { cn } from "@/lib/utils"; import { type AuditEvent, @@ -130,9 +132,11 @@ export function AuditTable({ }) { const [sorting, setSorting] = useState(INITIAL_SORT); const [columnFilters, setColumnFilters] = useState([]); + // The person reading the page: a row they started says "you", not their email. + const viewer = useQuery(currentUserQueryOptions()).data?.email ?? null; const columns = useMemo( - () => auditColumns(nameFor, storedNames, deploymentName, rowAction), - [nameFor, storedNames, deploymentName, rowAction], + () => auditColumns(nameFor, storedNames, deploymentName, viewer, rowAction), + [nameFor, storedNames, deploymentName, viewer, rowAction], ); const table = useTable({ features, @@ -365,6 +369,7 @@ function auditColumns( nameFor: NameFor, storedNames: boolean, deployment: string, + viewer: string | null, rowAction?: (event: AuditEvent) => React.ReactNode, ): ColumnDef[] { return [ @@ -429,13 +434,14 @@ function auditColumns( deployment={deployment} event={row.original} nameFor={nameFor} + viewer={viewer} /> ), enableSorting: false, }, { id: "startedBy", - accessorFn: (event) => startedByText(event, nameFor, deployment), + accessorFn: (event) => startedByText(event, nameFor, deployment, viewer), filterFn: anyOf, header: () => null, cell: () => null, @@ -454,7 +460,7 @@ function auditColumns( }, { id: "search", - accessorFn: (event) => searchTextOf(event, nameFor, deployment), + accessorFn: (event) => searchTextOf(event, nameFor, deployment, viewer), header: () => null, cell: () => null, enableSorting: false, diff --git a/app/src/components/bot-profile/access.tsx b/app/src/components/bot-profile/access.tsx index 91b5028a2a..90657a890e 100644 --- a/app/src/components/bot-profile/access.tsx +++ b/app/src/components/bot-profile/access.tsx @@ -180,7 +180,7 @@ function YourApps({ agent }: { agent: AgentProfile }) { ) : null} {giveable.error ? (

- Couldn't load your apps. Reload the page. + Couldn't load your apps. Try again in a moment.

) : rows.length === 0 ? ( me && skill.ownerUserId === me.id, - ); + const skills = (page.data ?? []).filter((skill) => skill.usableOnYourBots); const carried = new Set((held.data?.skills ?? []).map((skill) => skill.slug)); return ( - Couldn't load your skills. Reload the page. + Couldn't load your skills. Try again in a moment.

) : skills.length === 0 ? ( - Skills you write show up here. + Skills you write, and skills an admin gives your team, show up here. ) : ( @@ -385,7 +383,7 @@ function Granted({ if (!plugins.data) { return (

- Couldn't load what this Bot can use. Reload the page. + Couldn't load what this Bot can use. Try again in a moment.

); } @@ -416,7 +414,8 @@ function Granted({ > {kind === "apps" && apps.error ? (

- Couldn't check whether each app is ready for you. Reload the page. + Couldn't check whether each app is ready for you. Try again in a + moment.

) : null} {count === 0 && kind === "skills" ? ( diff --git a/app/src/components/bot-profile/activity.tsx b/app/src/components/bot-profile/activity.tsx index 2d7a8a9621..30b917765f 100644 --- a/app/src/components/bot-profile/activity.tsx +++ b/app/src/components/bot-profile/activity.tsx @@ -100,7 +100,7 @@ function linkFor(item: ActivityItem, agentId: string) { } } -function ActivityRow({ +export function ActivityRow({ agentId, item, live = false, @@ -425,7 +425,7 @@ export function BotActivitySections({ return (

- Couldn't load this Bot's activity. Reload the page. + Couldn't load this Bot's activity. Try again in a moment.

); @@ -459,7 +459,7 @@ export function BotActivitySections({ {/* The tasks failing to load leaves the rest listed, and says which part is missing. */} {taskList.error ? (

- Couldn't load this Bot's tasks. Reload the page. + Couldn't load this Bot's tasks. Try again in a moment.

) : null} {groups.length === 0 && !taskList.error ? ( diff --git a/app/src/components/bot-profile/attention.tsx b/app/src/components/bot-profile/attention.tsx index 41c2bdc2cf..a4a026a291 100644 --- a/app/src/components/bot-profile/attention.tsx +++ b/app/src/components/bot-profile/attention.tsx @@ -47,6 +47,24 @@ export function waitingOnYou(bot: BotAttention): number { return asksOf(bot) + bot.tasks.ready + bot.tasks.failed; } +/** + * How many things wait on the person across all their Bots: the one number every badge, bell and tab + * shows, in OpenBot's sidebar and in every skin. Counted once, by the server's rule (`waitingOnYou` + * per Bot), so a skin never counts its own way: one that counted the approval inbox said 1 while + * the Bots badge said 2, because a failed task or a task waiting on a question is in one and not the + * other. + */ +export function waitingAcross( + bots: readonly BotAttention[] | undefined, +): number { + return (bots ?? []).reduce((total, bot) => total + waitingOnYou(bot), 0); +} + +/** {@link waitingAcross}, read live, for whatever draws the number. */ +export function useWaitingCount(): number { + return waitingAcross(useQuery(botAttentionQueryOptions()).data); +} + const count = (total: number, one: string, many: string) => `${total} ${total === 1 ? one : many}`; @@ -266,7 +284,7 @@ export function BotsNavBadge({ onIcon = false }: { onIcon?: boolean } = {}) { useAttentionNotifications(attention.data); usePingNotifications(lastPing.data, attention.data); const bots = attention.data ?? []; - const waiting = bots.reduce((total, bot) => total + waitingOnYou(bot), 0); + const waiting = waitingAcross(bots); if (waiting > 0) { return ( - Couldn't load this Bot's settings. Reload the page. + Couldn't load this Bot's settings. Try again in a moment.

) : ( diff --git a/app/src/components/bot-profile/sharing.tsx b/app/src/components/bot-profile/sharing.tsx index 89f1406417..cc1cf1adde 100644 --- a/app/src/components/bot-profile/sharing.tsx +++ b/app/src/components/bot-profile/sharing.tsx @@ -15,6 +15,7 @@ import { } from "@/components/layout/page-shell"; import { SharedAppNotice } from "@/components/plugins/shared-app-notice"; import { Button } from "@/components/ui/button"; +import { Checkbox } from "@/components/ui/checkbox"; import { Dialog, DialogBody, @@ -24,7 +25,12 @@ import { DialogHeader, DialogTitle, } from "@/components/ui/dialog"; -import { Field, FieldGroup, FieldLabel } from "@/components/ui/field"; +import { + Field, + FieldDescription, + FieldGroup, + FieldLabel, +} from "@/components/ui/field"; import { Input } from "@/components/ui/input"; import { Item, @@ -54,6 +60,12 @@ import { teamBotsQueryOptions, unpublishTeamBotMutationOptions, } from "@/lib/team-bots"; +import { + type TeamSummary, + teamListQueryOptions, + teamOfValue, + teamValue, +} from "@/lib/teams/queries"; import { queryClient } from "@/query-client"; const list = (value: string) => @@ -62,13 +74,21 @@ const list = (value: string) => .map((part) => part.trim()) .filter(Boolean); +/** Everybody in the organization, as an assignment carries it. */ +const EVERYONE = "*"; +const EVERYONE_WORDS = "Everyone in the organization"; + /** - * Who else can use this Bot. Its owner publishes it to the whole team or to named people and groups; - * an administrator can also pin it at the top of a group's Bots lists. Each chat with a published - * Bot is private to the person having it; its owner cannot read it. + * Who else can use this Bot. Its owner publishes it to everyone in the organization or to named + * people and teams; an admin can also pin it at the top of a team's Bots lists. Each conversation + * with a published Bot is private to the person having it; its owner cannot read it. + * + * A Bot published to directory groups before there were teams keeps them: they are shown, sent + * back unchanged, and no new one is typed. New grants go to teams. */ export function SharingSections({ agent }: { agent: AgentProfile }) { const data = useQuery(teamBotsQueryOptions()); + const teams = useQuery(teamListQueryOptions()).data?.teams; const me = useQuery(currentUserQueryOptions()).data; const unpublish = useMutation(unpublishTeamBotMutationOptions(queryClient)); const [copied, setCopied] = useState(false); @@ -82,7 +102,7 @@ export function SharingSections({ agent }: { agent: AgentProfile }) { ); } const published = data.data.find((bot) => bot.botId === agent.id); - // A Bot is its owner's to publish, and one missing from the Team Bots list isn't published yet. + // A Bot is its owner's to publish, and one missing from the published list isn't published yet. const publishable = agent.mine && published === undefined; return ( @@ -99,20 +119,23 @@ export function SharingSections({ agent }: { agent: AgentProfile }) { - - - {published.audience === "team" - ? "To the whole team" - : `To ${[...(published.people ?? []), ...(published.groups ?? []).map((group) => `group ${group}`)].join(", ")}`} + + {/* + * Every name is read, so the line wraps instead of being cut at one. An address + * has nowhere to break, so it may break anywhere before it runs under the button. + */} + + {publishedTo(published, teams)} {published.visibleToTeam ? "Each person's conversations with it are private." - : "Teammates can't see it until it has a real name and a description."} + : "Other people can't see it until it has a real name and a description."} {agent.mine ? ( - + // On a phone the names keep the row's width and the button goes under them. +
@@ -359,11 +484,28 @@ function PublishDialog({ ); } +/** What an assignment is called: everyone, a team by its name, or a directory group by its own. */ +function assignmentName( + value: string, + teams: readonly TeamSummary[] | undefined, +): string { + if (value === EVERYONE) return EVERYONE_WORDS; + const teamId = teamOfValue(value); + if (teamId === null) return `Group ${value}`; + return teamName(teams, teamId) ?? "A team that was deleted"; +} + /** - * The groups an administrator has pinned this Bot for: one row each with a Remove, and a row that - * opens a dialog to add one. + * Who an admin has pinned this Bot for: one row each with a Remove, and a row that opens a dialog + * to add one. */ -function Assignments({ bot }: { bot: TeamBot }) { +function Assignments({ + bot, + teams, +}: { + bot: TeamBot; + teams: readonly TeamSummary[] | undefined; +}) { const remove = useMutation(assignTeamBotMutationOptions(queryClient)); const [assigning, setAssigning] = useState(false); const assigned = bot.assignedGroups ?? []; @@ -375,39 +517,42 @@ function Assignments({ bot }: { bot: TeamBot }) {

) : null} {assigned.length === 0 ? ( - + ) : null} - {assigned.map((name) => ( - - - - - - - {name === "*" ? "Whole team" : name} - - - - - - - - ))} + {assigned.map((value) => { + const name = assignmentName(value, teams); + return ( + + + + {value === EVERYONE ? : } + + + {name} + + + + + + + + ); + })} setAssigning(true)} type="button" />} size="sm" @@ -416,7 +561,7 @@ function Assignments({ bot }: { bot: TeamBot }) { - Assign to a group + Assign to a team or everyone @@ -424,24 +569,43 @@ function Assignments({ bot }: { bot: TeamBot }) { {assigning ? ( - setAssigning(false)} /> + setAssigning(false)} + teams={teams ?? []} + /> ) : null} ); } -/** One group to pin this Bot for, or * for the whole team. */ -function AssignDialog({ bot, onClose }: { bot: TeamBot; onClose: () => void }) { +/** One team to pin this Bot for, or everyone in the organization. What it already has is left out. */ +function AssignDialog({ + bot, + teams, + onClose, +}: { + bot: TeamBot; + teams: readonly TeamSummary[]; + onClose: () => void; +}) { const formId = useId(); const assign = useMutation(assignTeamBotMutationOptions(queryClient)); - const [group, setGroup] = useState(""); + const taken = new Set(bot.assignedGroups ?? []); + const choices: Record = Object.fromEntries( + [ + [EVERYONE, EVERYONE_WORDS] as const, + ...teams.map((team) => [teamValue(team.id), team.name] as const), + ].filter(([value]) => !taken.has(value)), + ); + const [group, setGroup] = useState(null); return ( !next && onClose()} open> - Assign {bot.name} to a group + Assign {bot.name} - It's pinned at the top of every member's Bots list. + It's pinned at the top of their Bots list, and they can't hide it. @@ -449,6 +613,7 @@ function AssignDialog({ bot, onClose }: { bot: TeamBot; onClose: () => void }) { id={formId} onSubmit={(event) => { event.preventDefault(); + if (group === null) return; assign.mutate( { botId: bot.botId, group }, { onSuccess: onClose }, @@ -456,13 +621,23 @@ function AssignDialog({ bot, onClose }: { bot: TeamBot; onClose: () => void }) { }} > - Group, or * - setGroup(event.target.value)} - placeholder="* for the whole team" + Assign to + {assign.error ? ( @@ -476,7 +651,7 @@ function AssignDialog({ bot, onClose }: { bot: TeamBot; onClose: () => void }) { Cancel } diff --git a/app/src/components/browser/browser-page.tsx b/app/src/components/browser/browser-page.tsx index bee6e10014..a3304c024f 100644 --- a/app/src/components/browser/browser-page.tsx +++ b/app/src/components/browser/browser-page.tsx @@ -84,7 +84,7 @@ export function BrowserPage() { return (

- Couldn't load your browser. Reload the page. + Couldn't load your browser. Try again in a moment.

} />
diff --git a/app/src/components/channels/channel-chat.tsx b/app/src/components/channels/channel-chat.tsx index 20e2580c1f..9ebea7c6ff 100644 --- a/app/src/components/channels/channel-chat.tsx +++ b/app/src/components/channels/channel-chat.tsx @@ -57,6 +57,7 @@ import { channelKeys, } from "@/lib/channels/queries"; import { runReply } from "@/lib/channels/run-reply"; +import { onBotSaidOffTheList } from "@/lib/channels/said-off-the-list"; import { onRunStartedAway, onTurnFinishedAway, @@ -67,8 +68,12 @@ import { turnsLeftRunning, turnsNoLongerAway, } from "@/lib/channels/turns-finished-away"; -import { onBotSaidOffTheList } from "@/lib/channels/said-off-the-list"; +import { publishedPlaygroundQueryOptions } from "@/lib/components/queries"; import { useConversationActivity } from "@/lib/computers/activity"; +import { + useConnectionLost, + useReconnected, +} from "@/lib/desktop/connection-lost"; import { channelAgentId, useActiveBot } from "@/lib/copilot/active-bot"; import { observeApprovalAgent, @@ -90,7 +95,12 @@ import { withStoredAnswers, } from "@/lib/copilot/repair-history"; import { releaseServerOwnedInterrupts } from "@/lib/copilot/server-owned-interrupts"; -import { followLastRun, stoppedReason } from "@/lib/copilot/stopped-turn"; +import { + failedRunReason, + followLastRun, + requestNotMade, + stoppedReason, +} from "@/lib/copilot/stopped-turn"; import { readThreadMessages, withCurrentA2uiVersions, @@ -98,7 +108,6 @@ import { import { modelCatalogueQueryOptions } from "@/lib/models/queries"; import { useConversationModel } from "@/lib/models/run-model"; import { useSkillCommands } from "@/lib/plugins/skill-commands"; -import { publishedPlaygroundQueryOptions } from "@/lib/components/queries"; import { askChannelAgent, messageText, @@ -666,7 +675,28 @@ export function ChannelChat({ if (isReady) openReadyGate.current(); }, [isReady]); + /** + * WHEN OPENBOT ANSWERS AGAIN, A CONVERSATION THAT HAD NO ANSWER FILLS IN BY ITSELF. Inside OpenBot + * Desktop connected to an OpenBot somewhere else, a conversation opened while that OpenBot did not + * answer has nothing to show: its join and the read of its history both came back from the relay. + * It used to stay that way until the person opened another conversation and came back. Now, when + * the connection line clears, a conversation whose join or read had no answer asks again: with an + * empty transcript it joins its thread again (`joins` reruns the join below), which also brings the + * runtime's connection back; with a transcript, it reads the stored history again and merges it, + * so a replay is never laid over messages already on screen. + */ + const [joins, setJoins] = useState(0); + const unanswered = useRef(false); + const connection = useConnectionLost(); + useReconnected(() => { + if (!unanswered.current) return; + unanswered.current = false; + if (agentRef.current.messages.length === 0) setJoins((count) => count + 1); + else pullHistoryRef.current?.(); + }); + // Join the gateway socket, restore durable history, then release the first-message gate. + // biome-ignore lint/correctness/useExhaustiveDependencies: `joins` is the join asked for again when OpenBot answers again. useEffect(() => { if (!isReady) return; let current = true; @@ -718,6 +748,7 @@ export function ChannelChat({ * typed afterwards waits on that gate, so a throw here would silence the conversation * rather than degrade it. History is restored below either way. */ + unanswered.current = true; } finally { lastRun.stop(); if (current) setReplaying(false); @@ -761,6 +792,7 @@ export function ChannelChat({ setHistoryAvailability(stored.availability); // A gateway snapshot may be partial; neither it nor a later send proves this read succeeded. setHistoryReadFailed(stored.availability === "unavailable"); + if (stored.availability === "unavailable") unanswered.current = true; } } finally { // Cleared on failure too: placeholders over an empty transcript promise messages that are @@ -781,6 +813,7 @@ export function ChannelChat({ channel.id, channel.threadId, runtimeAgentId, + joins, ]); /* @@ -865,6 +898,7 @@ export function ChannelChat({ if (delayMs === 1500 && !sawReady) { setHistoryAvailability("unavailable"); setHistoryReadFailed(true); + unanswered.current = true; } continue; } @@ -1001,14 +1035,17 @@ export function ChannelChat({ voicePending: voiceArchive.pending, voiceWaitedOut, }); - const historyNotice = channelHistoryNotice({ - restoring: historyLoading, - messageCount: agent.messages.length, - lastMessageAt: channel.lastMessageAt, - historyAvailability, - historyReadFailed, - unreadable, - }); + // While the connection line shows, it says why the history is missing; this does not repeat it. + const historyNotice = connection.lost + ? null + : channelHistoryNotice({ + restoring: historyLoading, + messageCount: agent.messages.length, + lastMessageAt: channel.lastMessageAt, + historyAvailability, + historyReadFailed, + unreadable, + }); const awaitingReply = useRef(false); /** @@ -1535,13 +1572,24 @@ export function ChannelChat({ * nine steps into a form) ended the turn with its steps on screen and nothing said. Only a * RUN_ERROR counts there: the Bot said it failed, where a Stop ends a run as finished, cancelled. */ - const fail = (message: string, laterRun = false) => { + const fail = ( + message: string, + laterRun = false, + /** A truer sentence that is still being asked for; nothing is drawn until it answers. */ + truer?: Promise, + ) => { if (!awaitingReply.current && !(laterRun && turnsRef.current > 0)) return; awaitingReply.current = false; // Both halves of one fact: the sentence the transcript shows, and the reason `deliver` throws // so the draft behind the turn is restored rather than counted as sent. See `turnFailure`. turnFailure.current = message; - setRunError(message); + if (!truer) return setRunError(message); + void truer.then((sentence) => { + // The next turn clears the failure; a sentence about the one before it is dropped. + if (turnFailure.current !== message) return; + turnFailure.current = sentence; + setRunError(sentence); + }); }; const subscription = agent.subscribe?.({ // Both surfaces fall back to the same sentence, from the same place, so a person who uses @@ -1561,7 +1609,18 @@ export function ChannelChat({ streamBroke.current = true; return; } - fail(stoppedReason(error)); + /* + * The run request itself was not made. That is the back end out of reach, or the Bot taken + * away from this person (the runtime answers 404 for a Bot that is not theirs), and the + * runtime client reports both the same way. `failedRunReason` asks the server which. + */ + fail( + stoppedReason(error), + false, + requestNotMade(error) + ? failedRunReason(error, runtimeAgentId) + : undefined, + ); }, onRunFinishedEvent: ({ event }) => { /* @@ -1773,7 +1832,7 @@ export function ChannelChat({ starterSuggestions={ channel.agentIds.length === 1 ? ( {voiceArchive.error && (

- Couldn’t load voice chats. Reload the page. + Couldn’t load voice chats. Try again in a moment.

)} + {/* The picked model stopped being offered: what this conversation uses now. */} + {runModel.notice && channel.active ? ( +

+ {runModel.notice} +

+ ) : null} {voiceContextNotice && (

{ expect(result.rejected[0].reason).toMatch(/too large/); }); + /** + * The Northwind story's invoice beat: a PDF invoice was refused at pick time with "isn't a file + * type you can attach", so the Bot never saw it. A PDF is staged like any other file, and the + * file dialog offers it. + */ + test("accepts a PDF invoice, and the file dialog offers PDFs", () => { + const invoice = file("invoice-NW-4471.pdf", "application/pdf", 200_000); + const result = screenPickedFiles([invoice], { alreadyStaged: 0 }); + + expect(result.rejected).toEqual([]); + expect(result.accepted).toEqual([invoice]); + expect(FILE_PICKER_ACCEPT.split(",")).toContain("application/pdf"); + expect(FILE_PICKER_ACCEPT.split(",")).toContain(".pdf"); + }); + + test("rejects a PDF over its limit, naming the limit", () => { + const big = file("scan.pdf", "application/pdf", MAX_DOCUMENT_BYTES + 1); + const result = screenPickedFiles([big], { alreadyStaged: 0 }); + + expect(result.accepted).toEqual([]); + expect(result.rejected[0].reason).toBe( + "'scan.pdf' is too large for a PDF. The limit is 8MB.", + ); + }); + test("rejects an oversized image", () => { const big = file("huge.png", "image/png", MAX_IMAGE_BYTES + 1); const result = screenPickedFiles([big], { alreadyStaged: 0 }); diff --git a/app/src/components/channels/composer/picked-files.ts b/app/src/components/channels/composer/picked-files.ts index cb3654a71a..5d07a28d22 100644 --- a/app/src/components/channels/composer/picked-files.ts +++ b/app/src/components/channels/composer/picked-files.ts @@ -1,6 +1,7 @@ import { classifyAttachment, MAX_ATTACHMENTS_PER_MESSAGE, + MAX_DOCUMENT_BYTES, MAX_FILE_BYTES, MAX_IMAGE_BYTES, mediaTypeOf, @@ -101,6 +102,16 @@ export function screenPickedFiles( continue; } + if (kind === "document" && file.size > MAX_DOCUMENT_BYTES) { + rejected.push( + reject( + file, + `'${file.name}' is too large for a PDF. The limit is ${formatBytes(MAX_DOCUMENT_BYTES)}.`, + ), + ); + continue; + } + // The LOOSE ceiling for a file nobody has named yet, because this screen does not know which // of the two limits applies to it. Guessing the tight one would put back exactly the refusal // this branch exists to remove; the server applies the right limit once it has the bytes. diff --git a/app/src/components/channels/group-chat.tsx b/app/src/components/channels/group-chat.tsx index e531286a50..22f353f896 100644 --- a/app/src/components/channels/group-chat.tsx +++ b/app/src/components/channels/group-chat.tsx @@ -178,7 +178,7 @@ export function GroupChat({ channelId }: { channelId: string }) { ? (names.get(message.agentId) ?? "A Bot no longer here") : message.ownerUserId === me?.id ? "You" - : "A teammate" + : "Someone else" } answeredBy={ message.answeredBy @@ -323,7 +323,7 @@ function GroupLine({ /> ) : (

- Asked a teammate for permission to use their own{" "} + Asked someone else for permission to use their own{" "} {message.consent.serverId} account.

) diff --git a/app/src/components/computer/handoff-resume-notice.tsx b/app/src/components/computer/handoff-resume-notice.tsx index 8d60f73734..fcc8b7560d 100644 --- a/app/src/components/computer/handoff-resume-notice.tsx +++ b/app/src/components/computer/handoff-resume-notice.tsx @@ -1,5 +1,5 @@ import { useEffect, useRef, useState } from "react"; -import { readControl } from "@/lib/computers/control"; +import { BOT_GONE, readControlOrGone } from "@/lib/computers/control"; import { forgetHandoff, hasActiveHandoff, @@ -44,8 +44,17 @@ export function HandoffResumeNotice({ let timer: ReturnType; const check = async () => { let stored = pendingHandoff(botId); + /* + * The Bot is not one this person can use any more (deleted, or shared with a team they were + * taken out of while this conversation was open): the read answers "not found", and would + * again every second for as long as the conversation stays open. It is the last read this + * conversation makes; opening it again asks once more. + */ + let gone = false; if (!stored && !noComputers) { - const state = await readControl(botId).catch(() => null); + const answer = await readControlOrGone(botId).catch(() => null); + gone = answer === BOT_GONE; + const state = answer === BOT_GONE ? null : answer; const request = state?.request; if (request?.toolCallId) { const candidate = { @@ -82,7 +91,7 @@ export function HandoffResumeNotice({ ? stored : null, ); - timer = setTimeout(() => void check(), 1000); + if (!gone) timer = setTimeout(() => void check(), 1000); }; void check(); return () => { diff --git a/app/src/components/edition/team-features-dialog.tsx b/app/src/components/edition/team-features-dialog.tsx index f89415f57b..402789fe2e 100644 --- a/app/src/components/edition/team-features-dialog.tsx +++ b/app/src/components/edition/team-features-dialog.tsx @@ -53,15 +53,18 @@ export const TEAM_FEATURE_GROUPS: readonly { features: readonly { title: string; icon: Icon }[]; }[] = [ { - title: "For your whole team", + title: "For your whole organization", features: [ { title: "Sign-in with Google, Microsoft or custom SSO", icon: IconLogin2, }, { title: "People, roles and admins", icon: IconUsers }, - { title: "Bots shared with your whole team", icon: IconUsersGroup }, - { title: "Learning shared across the team", icon: IconSchool }, + { + title: "Bots shared with your whole organization", + icon: IconUsersGroup, + }, + { title: "Learning shared across your organization", icon: IconSchool }, ], }, { diff --git a/app/src/components/layout/connection-banner.tsx b/app/src/components/layout/connection-banner.tsx new file mode 100644 index 0000000000..8969719e58 --- /dev/null +++ b/app/src/components/layout/connection-banner.tsx @@ -0,0 +1,80 @@ +import { IconCloudOff } from "@tabler/icons-react"; +import { useEffect } from "react"; +import { askWhetherOpenBotAnswers } from "@/lib/deployment/queries"; +import { useConnectionLost } from "@/lib/desktop/connection-lost"; + +/** The first check after the line appears, then twice as long each time, up to a minute. */ +const FIRST_CHECK_MS = 5_000; +const LONGEST_CHECK_MS = 60_000; + +/** + * One line saying the OpenBot this window is connected to can't be reached, on every screen, until + * it answers again. + * + * Only inside OpenBot Desktop connected to an OpenBot that runs somewhere else. There the page talks + * to the desktop app on this computer, which says when that OpenBot did not answer + * (`lib/desktop/reachability.ts`). This line names the cause once; the screens under it wait for + * OpenBot and say nothing of their own failures (`lib/desktop/connection-lost.ts`). A browser has its + * own cues for a site that is down, and a local Desktop has its own status, so neither draws it. + * + * It clears on the next request that gets an answer. While it shows the screens' reads wait, so it + * asks OpenBot itself now and then, backing off, and clears when it answers; the screens fill in + * then, by themselves. + * + * The same bar as the update banner, so it reads as OpenBot's own. + */ +export function ConnectionBanner() { + const { lost: showing, address } = useConnectionLost(); + + useEffect(() => { + if (!showing) return; + let wait = FIRST_CHECK_MS; + let stopped = false; + let timer: ReturnType; + const check = () => { + timer = setTimeout(async () => { + await askWhetherOpenBotAnswers(); + if (stopped) return; + wait = Math.min(wait * 2, LONGEST_CHECK_MS); + check(); + }, wait); + }; + check(); + return () => { + stopped = true; + clearTimeout(timer); + }; + }, [showing]); + + if (!showing || address === null) return null; + const said = `Can't reach ${hostOf(address)}. OpenBot will reconnect when it answers.`; + return ( + + ); +} + +/** "openbot.example.com", with its port when it has one. */ +function hostOf(address: string): string { + try { + return new URL(address).host || address; + } catch { + return address; + } +} diff --git a/app/src/components/manage/audit-page.tsx b/app/src/components/manage/audit-page.tsx index 6abe0402d1..3f1a45abcf 100644 --- a/app/src/components/manage/audit-page.tsx +++ b/app/src/components/manage/audit-page.tsx @@ -9,12 +9,13 @@ import { IconSearch, IconX, } from "@tabler/icons-react"; +import { isOpenBotActor } from "@openbot/shared/openbot-actor"; import { keepPreviousData, useInfiniteQuery, useQuery, } from "@tanstack/react-query"; -import { type ReactNode, useEffect, useState } from "react"; +import { type ReactNode, useEffect, useMemo, useState } from "react"; import { AskTheTrail, AuditAnswerNote } from "@/components/audit/ask-the-trail"; import type { AuditEvent } from "@/components/audit/audit-cells"; import { @@ -44,8 +45,11 @@ import { auditVocabularyQueryOptions, exportAuditTrail, } from "@/lib/audit/queries"; +import { currentUserQueryOptions } from "@/lib/auth/queries"; import { deploymentCapabilitiesQueryOptions } from "@/lib/deployment/queries"; import { useManagePaths } from "@/lib/manage-paths"; +import { useCurrentOrganizationId } from "@/lib/organizations/current"; +import { organizationMembersQueryOptions } from "@/lib/organizations/queries"; import { skillListQueryOptions } from "@/lib/skills/queries"; import { cn } from "@/lib/utils"; @@ -130,13 +134,52 @@ function withSkillTitles( }); } +/** What a row's payload calls somebody nobody could put a name to. */ +const NOBODY = new Set(["unattributed", "unknown"]); + +/** + * Each row a person started with the person named, where the row says only who by id. + * + * A Bot's actions are recorded on its person's authority (`actorUserId`) and carry no address of + * theirs, and many rows name the person only as the payload's `actor`: an address (an app given to + * a Bot, a routine switched on) or a person's id (a tool called for them). They read "Started by a + * person" with no name, while an organization's own rows named the address they recorded. The + * organization's members are what the page knows people by, and the signed-in person is always one + * of them. A person no longer a member, named by id alone, keeps "a person": the page has no name + * for them to give. + */ +export function withPeopleNamed( + events: AuditEvent[], + people: ReadonlyMap, +): AuditEvent[] { + return events.map((event) => { + if ((event.initiatorKind ?? "person") !== "person") return event; + const by = event.payload?.by; + if (typeof by === "string" && by.trim()) return event; + const actor = + typeof event.payload?.actor === "string" + ? event.payload.actor.trim() + : ""; + const fromPayload = + actor && !NOBODY.has(actor) && !isOpenBotActor(actor) + ? actor.includes("@") + ? actor + : people.get(actor) + : undefined; + const named = + (event.actorUserId ? people.get(event.actorUserId) : undefined) ?? + fromPayload; + return named ? { ...event, startedBy: named } : event; + }); +} + /** Admin's "Why?" on a row one of OpenBot's controls decided: see `what-if/why-button.tsx`. */ const whyFor = (event: AuditEvent) => explainable(event) ? : null; /** What the page says under its title in Admin, where an admin reviews every Bot against policy. */ const ADMIN_DESCRIPTION = - "Review Bot actions and actions blocked by this deployment’s policy."; + "Review Bot actions and actions blocked by this organization’s policy."; /** * `children` are sections only the team edition's Admin adds below the page's own (the admin's @@ -218,9 +261,27 @@ export function AuditPage({ ...skillListQueryOptions(), enabled: edition === "personal", }).data; - const rows = withSkillTitles( - oneRowPerAction(events.data?.pages.flatMap((page) => page.events) ?? []), - skills, + // Who started each row, by the address the People page shows: the members, and the reader. + const organization = useCurrentOrganizationId(); + const members = useQuery({ + ...organizationMembersQueryOptions(organization ?? ""), + enabled: edition === "team" && organization !== undefined, + }).data; + const reader = useQuery(currentUserQueryOptions()).data; + const people = useMemo( + () => + new Map([ + ...(members ?? []).map((member) => [member.id, member.email] as const), + ...(reader ? [[reader.id, reader.email] as const] : []), + ]), + [members, reader], + ); + const rows = withPeopleNamed( + withSkillTitles( + oneRowPerAction(events.data?.pages.flatMap((page) => page.events) ?? []), + skills, + ), + people, ); const nameFor = useBotNames(); const [exporting, setExporting] = useState(false); @@ -303,7 +364,7 @@ export function AuditPage({ {events.isPending ? null : events.isError && !events.isFetchNextPageError ? (

- Couldn't load these events. Reload the page. + Couldn't load these events. Try again in a moment.

) : ( - Couldn't load the app settings. Reload the page. + Couldn't load the app settings. Try again in a moment.

); } diff --git a/app/src/components/manage/computers-page.tsx b/app/src/components/manage/computers-page.tsx index eb44d5f77d..ec1bf4899a 100644 --- a/app/src/components/manage/computers-page.tsx +++ b/app/src/components/manage/computers-page.tsx @@ -37,6 +37,7 @@ import { } from "@/components/ui/item"; import { Separator } from "@/components/ui/separator"; import { useBotNames } from "@/lib/agents/bot-names"; +import { useBotListScope } from "@/lib/agents/list-scope"; import { agentListQueryOptions } from "@/lib/agents/queries"; import { currentUserQueryOptions } from "@/lib/auth/queries"; import { isOrganizationAdmin } from "@/lib/auth/roles"; @@ -155,7 +156,8 @@ export function ComputersPage({ enabled: (agentId === undefined || admin) && noComputers === false, }); const hostAccess = useQuery(hostAccessQueryOptions()); - const agents = useQuery(agentListQueryOptions()); + // Under Admin, every Bot in the organization (lib/agents/list-scope.tsx). + const agents = useQuery(agentListQueryOptions(false, useBotListScope())); const setState = useMutation(setComputerStateMutationOptions(queryClient)); const requestGrant = useMutation( requestHostFolderGrantMutationOptions(queryClient), @@ -177,7 +179,7 @@ export function ComputersPage({ * instead, because the top of this page is a long scroll away from them. */ const problem = fleet.error - ? "Couldn't load the computers. Reload the page." + ? "Couldn't load the computers. Try again in a moment." : null; const hostProblem = hostAccess.error ? hostAccess.error.message @@ -332,7 +334,7 @@ export function ComputersPage({ : "Its computer" : personal ? "Your Bots' browsers" - : "Computers in this deployment" + : "Computers in this organization" } > {setState.error ? ( diff --git a/app/src/components/manage/credentials-page.tsx b/app/src/components/manage/credentials-page.tsx index c01c6b6300..7acb9d1988 100644 --- a/app/src/components/manage/credentials-page.tsx +++ b/app/src/components/manage/credentials-page.tsx @@ -44,7 +44,7 @@ export function CredentialsPage() { Add {noun} } - description="Manage this deployment’s keys and tokens. Saved secrets cannot be viewed again." + description="Manage this organization’s keys and tokens. Saved secrets cannot be viewed again." title={paths.credentialsLabel} > @@ -68,7 +68,7 @@ export function CredentialsList() { if (credentials.error) return (

- Couldn't load {noun}s. Reload the page. + Couldn't load {noun}s. Try again in a moment.

); if (credentials.data.length === 0) diff --git a/app/src/components/manage/describe-grants.tsx b/app/src/components/manage/describe-grants.tsx index b2aff28ca4..f52e6df2c1 100644 --- a/app/src/components/manage/describe-grants.tsx +++ b/app/src/components/manage/describe-grants.tsx @@ -45,7 +45,10 @@ import { type AppGrantTranslation, translateAppGrants, } from "@/lib/app-grants/translate"; -import type { SharedUseApproval } from "@/lib/plugins/shared-use"; +import { + approvalNamesNobody, + type SharedUseApproval, +} from "@/lib/plugins/shared-use"; import { relativeTime } from "@/lib/relative-time"; import { queryClient } from "@/query-client"; @@ -383,7 +386,7 @@ export function DescribeGrants({ Let {botName} use the shared {appTitle} account? - + {save.error ? ( @@ -400,7 +403,7 @@ export function DescribeGrants({ Cancel + ) : ( - - ) : ( - - )} - {shownMeta.length ? ( -
- {shownMeta.map((piece, index) => ( - // biome-ignore lint/suspicious/noArrayIndexKey: the pieces are fixed per row. - - {index > 0 ? · : null} - {piece} - - ))} + )} + {shownMeta.length ? ( +
+ {shownMeta.map((piece, index) => ( + // biome-ignore lint/suspicious/noArrayIndexKey: the pieces are fixed per row. + + {index > 0 ? · : null} + {piece} + + ))} +
+ ) : null} +
+ {actions ? ( +
+ {actions}
) : null} - {actions ? ( -
{actions}
- ) : null} {open && more ?
{more}
: null} diff --git a/app/src/components/needs-you/board.tsx b/app/src/components/needs-you/board.tsx index c5bb7a5af5..36ab7b2889 100644 --- a/app/src/components/needs-you/board.tsx +++ b/app/src/components/needs-you/board.tsx @@ -2,7 +2,10 @@ import { IconChevronDown } from "@tabler/icons-react"; import { useQuery } from "@tanstack/react-query"; import { Fragment, type ReactNode, useState } from "react"; import { BotOrb } from "@/components/agents/bot-orb"; -import { useWaitingByBot } from "@/components/approvals/waiting"; +import { + useHeldAnswers, + useWaitingByBot, +} from "@/components/approvals/waiting"; import { PageSection } from "@/components/layout/page-shell"; import { SuggestionRow } from "@/components/suggestions/suggestion-row"; import { TaskBoardRow } from "@/components/tasks/task-row"; @@ -15,7 +18,9 @@ import { } from "@/lib/proactive"; import type { ReadFailure } from "@/lib/read-failure"; import { relativeTime } from "@/lib/relative-time"; +import { countsAsWaiting, heldByTaskOf } from "@/lib/tasks/groups"; import { useNeedsYou } from "./needs-you"; +import { StalledHandoffBoardRow, useStalledHandoffs } from "./stalled-handoffs"; /** How many of one Bot's finds show before the rest open in place. */ const FINDS_SHOWN = 3; @@ -35,18 +40,52 @@ const FINDS_SHOWN = 3; export function NeedsYouBoard({ agentId }: { agentId?: string }) { const agents = useQuery(agentListQueryOptions()); const settings = useQuery(proactiveSettingsQueryOptions()); - const waiting = useWaitingByBot(agentId); const list = useNeedsYou(agentId); + // A question or an action waiting in a task's own conversation is that task waiting: one row. + const waiting = useWaitingByBot( + agentId, + heldByTaskOf([...list.tasks, ...list.done]), + ); + + const stalledHandoffs = useStalledHandoffs(agentId); + // A task waiting on something in its thread is answered on its own row. + const heldAnswer = useHeldAnswers(); const blocked = new Map(waiting.byBot); + // Questions and actions each wait on the person; a task does when the badge counts it. + let waitingCount = [...waiting.byBot.values()].reduce( + (total, group) => total + group.rows.length, + 0, + ); for (const listed of list.tasks) { + if (countsAsWaiting(listed)) waitingCount += 1; const group = blocked.get(listed.task.agentId) ?? { rows: [], times: [] }; group.rows.push( - , + , ); - group.times.push(listed.task.updatedAt); + // Only what waits on the person says how long it has waited. + if (countsAsWaiting(listed)) group.times.push(listed.task.updatedAt); blocked.set(listed.task.agentId, group); } + // A hand-off that ran out of tries waits on the person too, and the badge counts it. + for (const stalled of stalledHandoffs) { + waitingCount += 1; + const group = blocked.get(stalled.botId) ?? { rows: [], times: [] }; + group.rows.push( + , + ); + group.times.push(stalled.item.at); + blocked.set(stalled.botId, group); + } const found = new Map(); for (const item of list.items) found.set(item.botId, [...(found.get(item.botId) ?? []), item]); @@ -77,10 +116,6 @@ export function NeedsYouBoard({ agentId }: { agentId?: string }) { const bot = (id: string) => agents.data?.find((agent) => agent.id === id); const settingOf = (id: string | null | undefined) => id ? settings.data?.find((setting) => setting.id === id) : undefined; - const waitingCount = [...blocked.values()].reduce( - (total, group) => total + group.rows.length, - 0, - ); const foundCount = list.items.length; return ( @@ -106,17 +141,21 @@ export function NeedsYouBoard({ agentId }: { agentId?: string }) { ) : null} {blocked.size ? ( - + {[...blocked].map(([botId, group]) => ( - Date.parse(at) < Date.parse(first) ? at : first, - ), - )}`} + note={ + group.times.length + ? `waiting since ${relativeTime( + group.times.reduce((first, at) => + Date.parse(at) < Date.parse(first) ? at : first, + ), + )}` + : "nothing waiting on you" + } > {group.rows} diff --git a/app/src/components/needs-you/needs-you.tsx b/app/src/components/needs-you/needs-you.tsx index b40c1c11c2..96d1a4608a 100644 --- a/app/src/components/needs-you/needs-you.tsx +++ b/app/src/components/needs-you/needs-you.tsx @@ -159,7 +159,14 @@ export function DoneTasks({ done }: { done: ListedTask[] }) { return ( setOpen(!open)} size="sm" variant="ghost"> + // Short on screen; to a screen reader it says which list it opens, beside Hidden's own Show. + } diff --git a/app/src/components/needs-you/stalled-handoffs.tsx b/app/src/components/needs-you/stalled-handoffs.tsx new file mode 100644 index 0000000000..4abebeecbb --- /dev/null +++ b/app/src/components/needs-you/stalled-handoffs.tsx @@ -0,0 +1,89 @@ +import { IconArrowsExchange } from "@tabler/icons-react"; +import { useQueries, useQuery } from "@tanstack/react-query"; +import { Link } from "@tanstack/react-router"; +import { BoardRow } from "@/components/needs-you/board-row"; +import { Button } from "@/components/ui/button"; +import { + type ActivityItem, + botActivityQueryOptions, + botAttentionQueryOptions, +} from "@/lib/bot-lifecycle/queries"; +import { relativeTime } from "@/lib/relative-time"; + +/** A hand-off a Bot asked for that ran out of tries: only the person can pick it up. */ +export type StalledHandoff = { botId: string; item: ActivityItem }; + +/** + * Every stalled hand-off the Bots badge counts, as rows to list: the badge counts them per Bot + * (`handoffs` on what the server says each Bot waits on), and each one is read from that Bot's own + * Activity, where it is the item that needs the person. Given a Bot, only that Bot's. Read only for + * a Bot the badge counts one for, so a quiet day reads nothing. + */ +export function useStalledHandoffs(agentId?: string): StalledHandoff[] { + const attention = useQuery(botAttentionQueryOptions()); + const asking = (attention.data ?? []) + .filter( + (bot) => + bot.handoffs > 0 && (agentId === undefined || bot.botId === agentId), + ) + .map((bot) => bot.botId); + const reads = useQueries({ + queries: asking.map((botId) => botActivityQueryOptions(botId)), + }); + const seen = new Set(); + const stalled: StalledHandoff[] = []; + asking.forEach((botId, at) => { + for (const item of reads[at]?.data?.inProgress ?? []) { + if (item.kind !== "handoff" || !item.needsYou || seen.has(item.id)) + continue; + seen.add(item.id); + stalled.push({ botId, item }); + } + }); + return stalled; +} + +/** A stalled hand-off on the Needs you board, in the board's one row shape, with Open into it. */ +export function StalledHandoffBoardRow({ + stalled, +}: { + stalled: StalledHandoff; +}) { + const { item } = stalled; + const { channelId } = item; + return ( + } + size="sm" + > + Open + + ) : ( + + ) + } + detail={item.detail} + icon={} + meta={[ + Stalled hand-off, + {relativeTime(item.at)}, + ]} + state="stalled" + title={item.title} + waiting + /> + ); +} diff --git a/app/src/components/organizations/invitations-page.tsx b/app/src/components/organizations/invitations-page.tsx new file mode 100644 index 0000000000..7af6e4090d --- /dev/null +++ b/app/src/components/organizations/invitations-page.tsx @@ -0,0 +1,210 @@ +import { IconBuilding, IconMail, IconMailOff } from "@tabler/icons-react"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import { Fragment, useState } from "react"; +import { PageEmpty, PageRows, PageShell } from "@/components/layout/page-shell"; +import { Button } from "@/components/ui/button"; +import { + Item, + ItemActions, + ItemContent, + ItemDescription, + ItemMedia, + ItemTitle, +} from "@/components/ui/item"; +import { Separator } from "@/components/ui/separator"; +import { useCurrentOrganizationId } from "@/lib/organizations/current"; +import { + acceptInvitationMutationOptions, + declineInvitationMutationOptions, +} from "@/lib/organizations/mutations"; +import { + type ReceivedInvitation, + receivedInvitationQueryOptions, + receivedInvitationsQueryOptions, +} from "@/lib/organizations/queries"; +import { receivedInvitationLine } from "@/lib/organizations/words"; +import { queryClient } from "@/query-client"; +import { useSwitchOrganization } from "./use-switch-organization"; + +/** + * One invitation as the person it was sent to sees it, in whatever state it is in. + * + * Waiting, it offers Accept and Decline. Accepting does not move the person: they keep working + * where they were, and the row then offers the switch. Expired, declined or canceled, it says so + * and offers nothing. A refusal is drawn under the row in the server's own sentence while the + * invitation still waits; one that expired or was canceled meanwhile is said by the row itself. + */ +export function InvitationRow({ + invitation, + onAccepted, +}: { + invitation: ReceivedInvitation; + /** Told when the person has joined, for a list the accepted invitation then leaves. */ + onAccepted?: (invitation: ReceivedInvitation) => void; +}) { + const accepting = acceptInvitationMutationOptions(queryClient); + const accept = useMutation({ + ...accepting, + /* + * Told before the lists are read again, not from the button's own callback: reading them again + * takes an accepted invitation out of the list, and this row with it, and a row that has gone + * hears nothing. Declaring an `onSuccess` over the spread replaces the factory's, so it is + * called here, by hand. + */ + onSuccess: async (...args) => { + onAccepted?.({ ...invitation, status: "accepted" }); + await accepting.onSuccess?.(...args); + }, + }); + const decline = useMutation(declineInvitationMutationOptions(queryClient)); + const switching = useSwitchOrganization(); + const current = useCurrentOrganizationId(); + const busy = accept.isPending || decline.isPending; + /* + * Only while the invitation still waits. A refusal that changed it (it expired or was canceled + * meanwhile) has the row read again, and the row's own line then says what happened, so the + * refusal under it would say the same thing twice in two wordings. + */ + const failure = + invitation.status === "pending" ? (accept.error ?? decline.error) : null; + const { name } = invitation.organization; + + return ( + <> + + + + + + {name} + + {receivedInvitationLine(invitation)} + + + {invitation.status === "pending" ? ( + + + + + ) : invitation.status === "accepted" && + invitation.organization.id !== current ? ( + + + + ) : null} + + {failure ? ( +

+ {failure.message} +

+ ) : null} + + ); +} + +/** + * The invitations waiting for the person, whichever organization they are working in. + * + * One they accept leaves the server's list, so it is kept here as accepted until they leave the + * page: the row is where the switch to the organization they just joined is offered. + */ +export function InvitationsPage() { + const invitations = useQuery(receivedInvitationsQueryOptions()); + const [accepted, setAccepted] = useState([]); + const listed = invitations.data ?? []; + const rows = [ + ...accepted.filter((one) => !listed.some((other) => other.id === one.id)), + ...listed, + ]; + + return ( + + {invitations.isPending ? null : invitations.error ? ( +

+ {invitations.error.message} +

+ ) : rows.length === 0 ? ( + + When somebody invites you to an organization, it shows here. + + ) : ( + + {rows.map((invitation, index) => ( + + + setAccepted((before) => [ + joined, + ...before.filter((one) => one.id !== joined.id), + ]) + } + /> + {index !== rows.length - 1 && } + + ))} + + )} +
+ ); +} + +/** + * The page an invitation's link opens: that one invitation, in whatever state it is in. One the + * server does not find for this person is said so, with the one thing to check. + */ +export function InvitationPage({ invitationId }: { invitationId: string }) { + const invitation = useQuery(receivedInvitationQueryOptions(invitationId)); + + return ( + + {invitation.isPending ? null : invitation.error ? ( +

+ {invitation.error.message} +

+ ) : invitation.data === null ? ( + + Check that you're signed in with the address it was sent to. + + ) : ( + + + + )} +
+ ); +} diff --git a/app/src/components/organizations/new-organization-dialog.tsx b/app/src/components/organizations/new-organization-dialog.tsx index f2d3683f59..8a07724295 100644 --- a/app/src/components/organizations/new-organization-dialog.tsx +++ b/app/src/components/organizations/new-organization-dialog.tsx @@ -92,8 +92,8 @@ function NewOrganizationForm() { New organization - A new organization starts with no Bots and no conversations. You - switch to it as soon as it's created. + A new organization starts with OpenBot's starter Bots and skills, + and no conversations. You switch to it as soon as it's created. diff --git a/app/src/components/organizations/organization-menu.tsx b/app/src/components/organizations/organization-menu.tsx index 5407e2f785..3412ea5940 100644 --- a/app/src/components/organizations/organization-menu.tsx +++ b/app/src/components/organizations/organization-menu.tsx @@ -1,4 +1,11 @@ -import { IconBuilding, IconPlus } from "@tabler/icons-react"; +import { + IconBuilding, + IconMail, + IconPlus, + IconSettings, + IconUserCircle, +} from "@tabler/icons-react"; +import { Link } from "@tanstack/react-router"; import { DropdownMenuGroup, DropdownMenuItem, @@ -7,24 +14,41 @@ import { DropdownMenuRadioItem, DropdownMenuSeparator, } from "@/components/ui/dropdown-menu"; -import type { OwnOrganizations } from "@/lib/organizations/queries"; +import { + Tooltip, + TooltipContent, + TooltipTrigger, +} from "@/components/ui/tooltip"; +import { useAnythingCut } from "@/hooks/use-anything-cut"; +import type { + OrganizationSummary, + OwnOrganizations, +} from "@/lib/organizations/queries"; import { cn } from "@/lib/utils"; /** * The person's organizations at the top of the account menu: the one they are working in checked, - * the others one click away, and New organization for somebody who may create one. + * the others one click away, its settings, the invitations waiting for their answer, and New + * organization for somebody who may create one. * - * Drawn only when there is something to switch to or create (`useOrganizationChoices`), so for + * Drawn only where OpenBot lists the person's organizations (`useOrganizationChoices`), so for * everybody else the menu is the one it always was. The rows take the menu's own item spacing from - * `itemClassName`, and a long name is cut short where the menu is as narrow as the sidebar. + * `itemClassName`. The account menu grows to a long name (`accountMenuClassName`), and a name too + * long even for that reads whole in a tooltip. */ export function OrganizationMenuItems({ choices, + invitationsWaiting, itemClassName, onNew, switching, }: { choices: OwnOrganizations; + /** + * How many invitations wait for the person's answer. The entry is drawn when some do, and without + * a count when they could not be read (null), so the page that says why is still one click away. + */ + invitationsWaiting: number | null; itemClassName: string; /** Open the New organization dialog, which lives outside the menu so it outlasts it. */ onNew: () => void; @@ -45,19 +69,43 @@ export function OrganizationMenuItems({ value={choices.currentId} > {choices.organizations.map((organization) => ( - - - {organization.name} - + organization={organization} + /> ))} + {choices.organizations.length > 0 ? ( + } + > + + Organization settings + + ) : null} + {invitationsWaiting === null || invitationsWaiting > 0 ? ( + } + > + + Invitations + {invitationsWaiting === null ? null : ( + + + , {invitationsWaiting} waiting + + )} + + ) : null} {choices.canCreate ? ( @@ -69,3 +117,46 @@ export function OrganizationMenuItems({ ); } + +/** + * One organization to switch to. A name the menu still cuts short reads whole in a tooltip, on + * hover and when the keyboard highlights the row (the menu highlights a row by focusing it), as the + * account row's own tooltip does. Cutting is only paint: the row's name for assistive technology is + * always the whole name. + */ +function OrganizationRow({ + className, + disabled, + organization, +}: { + className: string; + disabled: boolean; + organization: OrganizationSummary; +}) { + const { ref, cut } = useAnythingCut(); + return ( + + + } + > + {/* The person's own organization carries a person's mark; one they share, a building. */} + {organization.personal ? : } + {organization.name} + + + {organization.name} + + + ); +} diff --git a/app/src/components/organizations/organization-settings-page.tsx b/app/src/components/organizations/organization-settings-page.tsx new file mode 100644 index 0000000000..bb1db8d65f --- /dev/null +++ b/app/src/components/organizations/organization-settings-page.tsx @@ -0,0 +1,653 @@ +import { + IconBuilding, + IconChevronDown, + IconChevronRight, +} from "@tabler/icons-react"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import { useNavigate } from "@tanstack/react-router"; +import { Fragment, useEffect, useId, useState } from "react"; +import { + PageRows, + PageSection, + PageShell, +} from "@/components/layout/page-shell"; +import { Button } from "@/components/ui/button"; +import { + Dialog, + DialogBody, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog"; +import { + DropdownMenu, + DropdownMenuContent, + DropdownMenuItem, + DropdownMenuTrigger, +} from "@/components/ui/dropdown-menu"; +import { Field, FieldLabel } from "@/components/ui/field"; +import { Input } from "@/components/ui/input"; +import { + Item, + ItemActions, + ItemContent, + ItemDescription, + ItemMedia, + ItemTitle, +} from "@/components/ui/item"; +import { Separator } from "@/components/ui/separator"; +import { currentUserQueryOptions } from "@/lib/auth/queries"; +import { isOrganizationAdmin } from "@/lib/auth/roles"; +import { + changeMemberRoleMutationOptions, + leaveOrganizationMutationOptions, + removeOrganizationMemberMutationOptions, + renameOrganizationMutationOptions, +} from "@/lib/organizations/mutations"; +import { + type OrganizationMemberSummary, + type OrganizationSummary, + organizationMembersQueryOptions, + useOrganizationChoices, +} from "@/lib/organizations/queries"; +import { + initialsOf, + memberControl, + personName, + roleChangeQuestion, + roleInSentence, + roleName, +} from "@/lib/organizations/words"; +import { queryClient } from "@/query-client"; +import { SentInvitationsSection } from "./sent-invitations-section"; + +/** The API's cap on an organization's name, so the field stops where the server does. */ +const MAX_NAME_LENGTH = 100; + +/** + * The organization the person is working in: its name, who is in it, and the invitations it sent. + * + * What a row offers follows the person's role in this organization, which is the server's verdict + * from the list of their organizations: an owner or an admin renames it, invites people and removes + * members; a member reads the name and the members, and may leave. The server decides each of them + * again and its refusal is drawn in its own sentence. + */ +export function OrganizationSettingsPage() { + const choices = useOrganizationChoices(); + const organization = choices?.organizations.find( + (one) => one.id === choices.currentId, + ); + // Nothing until the list has answered. Where OpenBot lists none, the route never opens this page. + if (!organization) return null; + const canManage = isOrganizationAdmin(organization.role); + + return ( + + + + + + + + {canManage ? ( + + ) : null} + + ); +} + +/** + * The organization's name. A summary that opens a dialog for somebody who may rename it, and the + * name with nothing to click for a member. + */ +function NameRow({ + canManage, + organization, +}: { + canManage: boolean; + organization: OrganizationSummary; +}) { + const [open, setOpen] = useState(false); + const media = ( + + + + ); + if (!canManage) { + return ( + + {media} + + Name + + + + {organization.name} + + + + ); + } + return ( + <> + setOpen(true)} type="button" />} + size="sm" + > + {media} + + Name + {organization.name} + + + + + + + + ); +} + +function RenameOrganizationDialog({ + onOpenChange, + open, + organization, +}: { + onOpenChange: (open: boolean) => void; + open: boolean; + organization: OrganizationSummary; +}) { + const formId = useId(); + const rename = useMutation(renameOrganizationMutationOptions(queryClient)); + const { reset } = rename; + const [name, setName] = useState(organization.name); + + // Each opening starts from the name it has, and a refusal from the last one is not news about this one. + useEffect(() => { + if (open) { + setName(organization.name); + reset(); + } + }, [open, organization.name, reset]); + + const save = async () => { + try { + await rename.mutateAsync({ + organizationId: organization.id, + name: name.trim(), + }); + } catch { + // The error is on the mutation and drawn below; staying open says "not done". + return; + } + onOpenChange(false); + }; + + return ( + + + + Rename organization + + Everybody in this organization sees the new name. + + + +
{ + event.preventDefault(); + if (!rename.isPending && name.trim()) void save(); + }} + > + + Name + { + setName(event.target.value); + reset(); + }} + value={name} + /> + +
+ {rename.error ? ( +

+ {rename.error.message} +

+ ) : null} +
+ + + + +
+
+ ); +} + +/** A person's picture, or their initials on the tint the account row uses. */ +function PersonAvatar({ person }: { person: OrganizationMemberSummary }) { + return ( +
+ {person.image ? ( + + ) : ( + initialsOf(person) + )} +
+ ); +} + +/** A member and the role they are about to be given. */ +type RoleChange = { + member: OrganizationMemberSummary; + role: OrganizationMemberSummary["role"]; +}; + +/** + * Who is in the organization, with each person's role, and what their row offers: a Role menu + * listing the roles the server says the person looking may give them (`assignableRoles`), and + * Remove or Leave where the membership can end (`removable`). + */ +function MembersSection({ + organization, +}: { + organization: OrganizationSummary; +}) { + const members = useQuery(organizationMembersQueryOptions(organization.id)); + const me = useQuery(currentUserQueryOptions()).data; + const changeRole = useMutation(changeMemberRoleMutationOptions(queryClient)); + // Kept while its dialog closes, so the question does not lose its name on the way out. + const [removing, setRemoving] = useState( + null, + ); + const [removeOpen, setRemoveOpen] = useState(false); + const [leaveOpen, setLeaveOpen] = useState(false); + const [changing, setChanging] = useState(null); + const [changeOpen, setChangeOpen] = useState(false); + const viewer = { id: me?.id, role: organization.role }; + + // Making somebody an owner, and stepping down, are asked about first. The rest apply at once. + const giveRole = (change: RoleChange) => { + changeRole.reset(); + if (roleChangeQuestion(change.member, change.role, me?.id)) { + setChanging(change); + setChangeOpen(true); + return; + } + changeRole.mutate({ + organizationId: organization.id, + personId: change.member.id, + role: change.role, + }); + }; + + return ( + + {members.isPending ? null : members.error ? ( +

+ {members.error.message} +

+ ) : ( + + {members.data.map((member, index) => { + const control = memberControl(member, viewer); + const name = personName(member); + return ( + + + + + + + + {name} + {member.id === me?.id ? ( + + You + + ) : null} + + + {member.name?.trim() + ? `${member.email} · ${roleName(member.role)}` + : roleName(member.role)} + + + {control || member.assignableRoles.length > 0 ? ( + + {member.assignableRoles.length > 0 ? ( + + + } + > + Role + + + + {member.assignableRoles.map((role) => ( + giveRole({ member, role })} + > + {roleName(role)} + + ))} + + + ) : null} + {!control ? null : control === "leave" ? ( + + ) : ( + + )} + + ) : null} + + {index !== members.data.length - 1 && } + + ); + })} + + )} + {changeRole.error ? ( +

+ {changeRole.error.message} +

+ ) : null} + {changing ? ( + + ) : null} + {removing ? ( + + ) : null} + +
+ ); +} + +/** + * Asks before making somebody an owner, or before the person steps down from owner, saying what + * it means, and then changes the role. A refusal stays in the dialog. + */ +function ChangeRoleDialog({ + change, + onOpenChange, + open, + organization, + viewerId, +}: { + change: RoleChange; + onOpenChange: (open: boolean) => void; + open: boolean; + organization: OrganizationSummary; + viewerId: string | undefined; +}) { + const changeRole = useMutation(changeMemberRoleMutationOptions(queryClient)); + const { reset } = changeRole; + // A refusal from a previous attempt is not news about this one. + useEffect(() => { + if (open) reset(); + }, [open, reset]); + const steppingDown = + roleChangeQuestion(change.member, change.role, viewerId) === "step-down"; + + const confirm = async () => { + try { + await changeRole.mutateAsync({ + organizationId: organization.id, + personId: change.member.id, + role: change.role, + }); + } catch { + // The error is on the mutation and drawn below; staying open says "not done". + return; + } + onOpenChange(false); + }; + + return ( + + + + + {steppingDown + ? `Step down as an owner of ${organization.name}?` + : `Make ${personName(change.member)} an owner of ${organization.name}?`} + + + {steppingDown + ? `You become ${roleInSentence(change.role)} and can no longer change who owns this organization. To be an owner again, another owner has to make you one.` + : "An owner can rename the organization, invite and remove people, and change who owns it. You stay an owner too."} + + + {changeRole.error ? ( +

+ {changeRole.error.message} +

+ ) : null} + + + + +
+
+ ); +} + +/** Asks before removing somebody, naming them, and removes them. A refusal stays in the dialog. */ +function RemoveMemberDialog({ + member, + onOpenChange, + open, + organization, +}: { + member: OrganizationMemberSummary; + onOpenChange: (open: boolean) => void; + open: boolean; + organization: OrganizationSummary; +}) { + const remove = useMutation( + removeOrganizationMemberMutationOptions(queryClient), + ); + const { reset } = remove; + // A refusal from a previous attempt is not news about this one. + useEffect(() => { + if (open) reset(); + }, [open, reset]); + + const confirm = async () => { + try { + await remove.mutateAsync({ + organizationId: organization.id, + personId: member.id, + }); + } catch { + // The error is on the mutation and drawn below; staying open says "not done". + return; + } + onOpenChange(false); + }; + + return ( + + + + + Remove {personName(member)} from {organization.name}? + + + They keep their account and their other organizations. What they + made here stays here. + + + {remove.error ? ( +

+ {remove.error.message} +

+ ) : null} + + + + +
+
+ ); +} + +/** + * Asks before the person leaves, and leaves. They are then working in another of their + * organizations, from home, as after a switch. + */ +function LeaveOrganizationDialog({ + onOpenChange, + open, + organization, +}: { + onOpenChange: (open: boolean) => void; + open: boolean; + organization: OrganizationSummary; +}) { + const navigate = useNavigate(); + const leave = useMutation( + leaveOrganizationMutationOptions(queryClient, async () => { + await navigate({ to: "/" }); + }), + ); + const { reset } = leave; + // A refusal from a previous attempt is not news about this one. + useEffect(() => { + if (open) reset(); + }, [open, reset]); + + return ( + + + + Leave {organization.name}? + + You lose access to its Bots and conversations. What you made here + stays here. To come back, somebody has to invite you again. + + + {leave.error ? ( +

+ {leave.error.message} +

+ ) : null} + + + + +
+
+ ); +} diff --git a/app/src/components/organizations/sent-invitations-section.tsx b/app/src/components/organizations/sent-invitations-section.tsx new file mode 100644 index 0000000000..7901c1d960 --- /dev/null +++ b/app/src/components/organizations/sent-invitations-section.tsx @@ -0,0 +1,414 @@ +import { IconMail, IconMailPlus } from "@tabler/icons-react"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import { Fragment, useEffect, useId, useState } from "react"; +import { + PageEmpty, + PageRows, + PageSection, +} from "@/components/layout/page-shell"; +import { copyText } from "@/components/settings/linked-accounts"; +import { Button } from "@/components/ui/button"; +import { + Dialog, + DialogBody, + DialogContent, + DialogDescription, + DialogFooter, + DialogHeader, + DialogTitle, +} from "@/components/ui/dialog"; +import { + Field, + FieldDescription, + FieldGroup, + FieldLabel, +} from "@/components/ui/field"; +import { Input } from "@/components/ui/input"; +import { + Item, + ItemActions, + ItemContent, + ItemDescription, + ItemMedia, + ItemTitle, +} from "@/components/ui/item"; +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, + SelectValue, +} from "@/components/ui/select"; +import { Separator } from "@/components/ui/separator"; +import type { + AssignableRole, + OrganizationInvitationResponse, +} from "@/lib/api/generated/model"; +import { + cancelSentInvitationMutationOptions, + inviteToOrganizationMutationOptions, +} from "@/lib/organizations/mutations"; +import { + type OrganizationSummary, + type SentInvitation, + sentInvitationsQueryOptions, +} from "@/lib/organizations/queries"; +import { + invitationLink, + roleName, + sentInvitationLine, +} from "@/lib/organizations/words"; +import { queryClient } from "@/query-client"; + +/** The API's cap on an address, so the field stops where the server does. */ +const MAX_EMAIL_LENGTH = 320; + +const ROLES: Record = { + member: roleName("member"), + admin: roleName("admin"), +}; + +/** + * A button that copies an invitation's link and says so. Where the browser will not copy (a + * plain-http address, a refused permission), `onFailed` lets the caller show the link to copy by hand. + */ +function CopyLinkButton({ + label, + link, + onFailed, +}: { + /** Names the invitation for a screen reader where several rows each have this button. */ + label?: string; + link: string; + onFailed: (failed: boolean) => void; +}) { + const [copied, setCopied] = useState(false); + // "Copied" for a moment, then the button offers itself again. + useEffect(() => { + if (!copied) return; + const timer = setTimeout(() => setCopied(false), 2000); + return () => clearTimeout(timer); + }, [copied]); + return ( + + ); +} + +/** + * The invitations this organization sent that nobody has accepted: waiting, expired or declined. + * Drawn only for its owner and admins, who are the ones the server lets read them. + */ +export function SentInvitationsSection({ + organization, +}: { + organization: OrganizationSummary; +}) { + const invitations = useQuery(sentInvitationsQueryOptions(organization.id)); + const [inviting, setInviting] = useState(false); + + return ( + setInviting(true)} size="sm" variant="outline"> + + Invite + + } + description="Invite somebody by email. An invitation lasts 7 days." + title="Invitations" + > + {invitations.isPending ? null : invitations.error ? ( +

+ {invitations.error.message} +

+ ) : invitations.data.length === 0 ? ( + + An invitation shows here until the person accepts it. + + ) : ( + + {invitations.data.map((invitation, index) => ( + + + {index !== invitations.data.length - 1 && } + + ))} + + )} + +
+ ); +} + +/** + * One invitation with its own Cancel, so a refusal is drawn under the row it is about. Only one + * still waiting has a link worth passing on. + */ +function SentInvitationRow({ + invitation, + organizationId, +}: { + invitation: SentInvitation; + organizationId: string; +}) { + const cancel = useMutation(cancelSentInvitationMutationOptions(queryClient)); + const [copyFailed, setCopyFailed] = useState(false); + const link = invitationLink(invitation.id); + return ( + <> + + + + + + + {invitation.email} + + {sentInvitationLine(invitation)} + + + {invitation.status === "pending" ? ( + + ) : null} + + + + {copyFailed ? ( +

+ Couldn't copy the link. Copy it yourself:{" "} + {link} +

+ ) : null} + {cancel.error ? ( +

+ {cancel.error.message} +

+ ) : null} + + ); +} + +/** + * Invites an address with a role, then says what happened in the same dialog: OpenBot emailed the + * person, or the inviter copies the link and passes it on. A refusal stays in the dialog in the + * server's own sentence, with the address still typed. + */ +function InviteDialog({ + onOpenChange, + open, + organization, +}: { + onOpenChange: (open: boolean) => void; + open: boolean; + organization: OrganizationSummary; +}) { + const formId = useId(); + const invite = useMutation(inviteToOrganizationMutationOptions(queryClient)); + const { reset } = invite; + const [email, setEmail] = useState(""); + const [role, setRole] = useState("member"); + const [sent, setSent] = useState(null); + + // Each opening starts empty, and what the last one said is not news about this one. + useEffect(() => { + if (open) { + setEmail(""); + setRole("member"); + setSent(null); + reset(); + } + }, [open, reset]); + + const send = async () => { + try { + setSent( + await invite.mutateAsync({ + organizationId: organization.id, + email: email.trim(), + role, + }), + ); + } catch { + // The error is on the mutation and drawn below; staying on the form says "not done". + } + }; + + return ( + + + {sent ? ( + onOpenChange(false)} sent={sent} /> + ) : ( + <> + + Invite to {organization.name} + + They see the invitation in OpenBot when they sign in with this + address. It lasts 7 days. + + + +
{ + event.preventDefault(); + if (!invite.isPending && email.trim()) void send(); + }} + > + + + Email + { + setEmail(event.target.value); + reset(); + }} + placeholder="name@example.com" + type="email" + value={email} + /> + + + Role + + + An admin can rename the organization, invite people and + remove members. + + + +
+ {invite.error ? ( +

+ {invite.error.message} +

+ ) : null} +
+ + + + + + )} +
+
+ ); +} + +/** What happened to an invitation just made: emailed, or a link for the inviter to pass on. */ +function InvitationSent({ + onDone, + sent, +}: { + onDone: () => void; + sent: OrganizationInvitationResponse; +}) { + const [copyFailed, setCopyFailed] = useState(false); + const { email, id } = sent.invitation; + const link = invitationLink(id); + return ( + <> + + + {sent.delivery === "emailed" ? "Invitation sent" : "Invitation ready"} + + + {sent.delivery === "emailed" + ? `We emailed ${email} an invitation.` + : `Copy the link and send it to ${email}.`} + + + {sent.delivery === "link" ? ( + +
+ {/* A fill, not the card colour, which a dialog's own surface already is. */} + + {link} + + +
+ {copyFailed ? ( +

+ Couldn't copy the link. Select it and copy it yourself. +

+ ) : null} +
+ ) : null} + + + + + ); +} diff --git a/app/src/components/plugins/access-requests.tsx b/app/src/components/plugins/access-requests.tsx index a4b95a8f47..9ae6517506 100644 --- a/app/src/components/plugins/access-requests.tsx +++ b/app/src/components/plugins/access-requests.tsx @@ -59,7 +59,7 @@ export function AccessRequestsSection({ app }: { app?: string }) { return (

- Couldn't load access requests. Reload the page. + Couldn't load access requests. Try again in a moment.

); diff --git a/app/src/components/plugins/account-mode-dialog.tsx b/app/src/components/plugins/account-mode-dialog.tsx index 839eda8e66..05249ea708 100644 --- a/app/src/components/plugins/account-mode-dialog.tsx +++ b/app/src/components/plugins/account-mode-dialog.tsx @@ -13,7 +13,8 @@ import { accountModePreview, setAccountModeMutationOptions, } from "@/lib/apps/mutations"; -import { describeApproval } from "@/lib/plugins/shared-use"; +import { approvalNamesTeam, describeApproval } from "@/lib/plugins/shared-use"; +import { teamListQueryOptions } from "@/lib/teams/queries"; /** * The one moment an administrator decides between people's own accounts and one shared account. @@ -50,6 +51,13 @@ export function AccountModeDialog({ queryFn: () => accountModePreview(serverId, target), enabled: open, }); + // A Bot's approval keeps a team's id; its name comes from the organization's teams, read once. + const teams = useQuery({ + ...teamListQueryOptions(), + enabled: + open && + (preview.data?.bots ?? []).some((bot) => approvalNamesTeam(bot.exposure)), + }).data?.teams; const change = useMutation({ ...setAccountModeMutationOptions(queryClient), onSuccess: () => onOpenChange(false), @@ -89,7 +97,7 @@ export function AccountModeDialog({ {names[bot.botId] ?? bot.botId} - : {describeApproval(bot.exposure)} + : {describeApproval(bot.exposure, teams)} ))} diff --git a/app/src/components/plugins/app-access-action.tsx b/app/src/components/plugins/app-access-action.tsx index 8e449ca538..9b5057161d 100644 --- a/app/src/components/plugins/app-access-action.tsx +++ b/app/src/components/plugins/app-access-action.tsx @@ -266,8 +266,11 @@ function AdminAction({ access.state !== "shared_not_connected" ? ["Set it up", `Set up ${name}`] : access.requestKind - ? ["Connect the team account", `Connect the team ${name} account`] - : ["Reconnect the team account", `Reconnect the team ${name} account`]; + ? ["Connect the shared account", `Connect the shared ${name} account`] + : [ + "Reconnect the shared account", + `Reconnect the shared ${name} account`, + ]; /* * A broker with no key is set up on its directory, which is a page of its own in the personal * edition. There `/connections/composio` would read as an app called "composio" and say there is diff --git a/app/src/components/plugins/broker-directory.tsx b/app/src/components/plugins/broker-directory.tsx index 49cda596cb..b3255ee019 100644 --- a/app/src/components/plugins/broker-directory.tsx +++ b/app/src/components/plugins/broker-directory.tsx @@ -12,7 +12,7 @@ import { type ConnectInNewTab, useConnectInNewTab, } from "@/components/plugins/connect-in-new-tab"; -import { AppInitial } from "@/components/plugins/plugin-logo"; +import { AppInitial, LOGO_TILE } from "@/components/plugins/plugin-logo"; import { Button } from "@/components/ui/button"; import { Input } from "@/components/ui/input"; import { @@ -33,6 +33,11 @@ import { directorySlug, } from "@/lib/apps/queries"; import { useManagePaths } from "@/lib/manage-paths"; +import { + type DirectoryAppState, + directoryAppState, + directoryConnect, +} from "@/lib/plugins/directory-state"; import { consentBreadth, coverageWarning, @@ -46,11 +51,6 @@ import { type PluginsProvider, providerVocabulary, } from "@/lib/plugins/provider-vocabulary"; -import { - type DirectoryAppState, - directoryAppState, - directoryConnect, -} from "@/lib/plugins/directory-state"; import { connectionsQueryOptions } from "@/lib/plugins/queries"; /** @@ -318,7 +318,7 @@ export function BrokerDirectory({ provider }: { provider: PluginsProvider }) { > {query ? `No app matches "${query}".` - : "No apps to show yet. Reload the page to try again."} + : "No apps to show yet. Try again in a moment."}
) : ( <> @@ -346,7 +346,10 @@ export function BrokerDirectory({ provider }: { provider: PluginsProvider }) { > {/* The vendor's own mark where the broker supplies one, and its initial where it does not, so a list of third parties still has a fixed left edge. */} - + {entry.logo ? ( ) : ( diff --git a/app/src/components/plugins/brokered-account-row.tsx b/app/src/components/plugins/brokered-account-row.tsx index 73090c488a..5fb1c441d7 100644 --- a/app/src/components/plugins/brokered-account-row.tsx +++ b/app/src/components/plugins/brokered-account-row.tsx @@ -484,7 +484,7 @@ export function useBrokeredAccount(input: { */ if (start === null) { report( - "This app connects with a key, not a sign-in page, so nothing was connected. Reload the page and press Connect again.", + "This app connects with a key, not a sign-in page, so nothing was connected. Open this app again from Connections and press Connect.", ); return; } @@ -650,7 +650,7 @@ export function useBrokeredAccount(input: { } if (start === null) { report( - "This app connects with a key, not a sign-in page, so nothing was connected. Reload the page and press Connect again.", + "This app connects with a key, not a sign-in page, so nothing was connected. Open this app again from Connections and press Connect.", ); return; } diff --git a/app/src/components/plugins/plugin-logo.tsx b/app/src/components/plugins/plugin-logo.tsx index d2c279a25f..9a27a1a425 100644 --- a/app/src/components/plugins/plugin-logo.tsx +++ b/app/src/components/plugins/plugin-logo.tsx @@ -1,5 +1,14 @@ import { IconPlug } from "@tabler/icons-react"; import { useState } from "react"; +import { cn } from "@/lib/utils"; + +/** + * ON A WHITE TILE IN DARK MODE, BECAUSE SOME MARKS DISAPPEAR WITHOUT ONE. GitHub's mark is black, + * and on the dark page it all but vanished. A vendor's artwork is never recoloured, so dark mode + * gives every mark a white tile instead: the same rule the framework marks follow + * (`agents/harness-mark.tsx`). Every mark reads on white. + */ +export const LOGO_TILE = "rounded-sm dark:bg-white dark:p-0.5"; /** * An app's logo, or its initial where it has none. @@ -24,7 +33,7 @@ export function PluginLogo({ setFailedUrl(logo)} diff --git a/app/src/components/plugins/shared-approval-fields.tsx b/app/src/components/plugins/shared-approval-fields.tsx index e0d85b7af5..bfebecb647 100644 --- a/app/src/components/plugins/shared-approval-fields.tsx +++ b/app/src/components/plugins/shared-approval-fields.tsx @@ -1,7 +1,23 @@ +import { IconBuildingBank, IconUsersGroup } from "@tabler/icons-react"; +import { useQuery } from "@tanstack/react-query"; +import { Fragment, type ReactNode, useId } from "react"; +import { Button } from "@/components/ui/button"; +import { Checkbox } from "@/components/ui/checkbox"; import { - describeApproval, + Item, + ItemActions, + ItemContent, + ItemDescription, + ItemMedia, + ItemTitle, +} from "@/components/ui/item"; +import { + type ApprovalMember, + approvalNamesNobody, type SharedUseApproval, } from "@/lib/plugins/shared-use"; +import { MISSING_TEAM } from "@/lib/teams/names"; +import { teamListQueryOptions } from "@/lib/teams/queries"; export function sharedSectionSentence( effect: "read" | "write", @@ -13,10 +29,18 @@ export function sharedSectionSentence( : "Anyone who can use this Bot can read what this account can read."; } +const AUDIENCES: { audience: SharedUseApproval["audience"]; label: string }[] = + [ + { audience: "owner", label: "Only its owner" }, + { audience: "people", label: "Named teams and people" }, + { audience: "team", label: "Everyone" }, + ]; + /** * Who may use a shared account through one Bot: the audience the Bot has now, offered as the - * default, and only ever NARROWED here. Named people are offered only when the Bot is published to - * named people, because that list is what a `people` approval records. + * default, which an admin can change here. Only its owner, everyone in the organization, or the + * teams the admin names. Whoever the audience already names (people, and directory groups from + * before there were teams) is kept and shown under the named choice. */ export function SharedApprovalFields({ value, @@ -25,41 +49,33 @@ export function SharedApprovalFields({ value: SharedUseApproval; onChange: (next: SharedUseApproval) => void; }) { - const named = value.audience === "people" || value.members.length > 0; - const options: { audience: SharedUseApproval["audience"]; label: string }[] = - [ - { audience: "owner", label: "Only its owner" }, - ...(named - ? [ - { - audience: "people" as const, - label: `Named: ${describeApproval({ ...value, audience: "people", outsideInput: false })}`, - }, - ] - : []), - { audience: "team", label: "Everyone" }, - ]; return ( -
+
Who can use the shared account through this Bot - {options.map((option) => ( - + {AUDIENCES.map((option) => ( + + + {/* Under the choice it belongs to, so the teams never read as part of the one after. */} + {option.audience === "people" && value.audience === "people" ? ( + + ) : null} + ))}
+ ); +} diff --git a/app/src/components/teams/new-team-page.tsx b/app/src/components/teams/new-team-page.tsx new file mode 100644 index 0000000000..6d39e36f18 --- /dev/null +++ b/app/src/components/teams/new-team-page.tsx @@ -0,0 +1,226 @@ +import { IconUsersGroup } from "@tabler/icons-react"; +import { useForm } from "@tanstack/react-form"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import { Link, useNavigate } from "@tanstack/react-router"; +import { TeamPage } from "@/components/edition/for-a-team"; +import { PageCard, PageEmpty, PageShell } from "@/components/layout/page-shell"; +import { Button } from "@/components/ui/button"; +import { + Field, + FieldDescription, + FieldError, + FieldGroup, + FieldLabel, +} from "@/components/ui/field"; +import { Input } from "@/components/ui/input"; +import { + Select, + SelectContent, + SelectGroup, + SelectItem, + SelectTrigger, + SelectValue, +} from "@/components/ui/select"; +import { Textarea } from "@/components/ui/textarea"; +import { + NO_PARENT, + type TeamFormValues, + teamFormSchema, + teamInputFrom, +} from "@/lib/teams/form"; +import { createTeamMutationOptions } from "@/lib/teams/mutations"; +import { possibleParents, teamListQueryOptions } from "@/lib/teams/queries"; +import { queryClient } from "@/query-client"; + +const BACK = { + label: "Teams", + linkProps: { to: "/teams" as const }, +}; +const DESCRIPTION = "Name the team. You add its people on the next screen."; + +/** What the parent Select shows for each value: without it the trigger would draw a team's id. */ +export function parentLabels( + teams: readonly { id: string; name: string }[], +): Record { + return { + [NO_PARENT]: "None", + ...Object.fromEntries(teams.map((team) => [team.id, team.name])), + }; +} + +/** + * Creating a team, on a screen of its own reached from the list's New team. On success the person + * lands on the new team's page, where its people are added. + */ +function NewTeam() { + const navigate = useNavigate(); + const list = useQuery(teamListQueryOptions()); + const createTeam = useMutation(createTeamMutationOptions(queryClient)); + const parents = possibleParents(list.data?.teams ?? []); + const defaultValues: TeamFormValues = { + name: "", + description: "", + parentTeamId: NO_PARENT, + }; + const form = useForm({ + defaultValues, + validators: { onSubmit: teamFormSchema }, + onSubmit: async ({ value }) => { + const team = await createTeam.mutateAsync(teamInputFrom(value)); + await navigate({ + to: "/teams/$teamId", + params: { teamId: team.id }, + }); + }, + }); + + // Reached by its address by somebody the server would refuse: say so before they fill it in. + if (list.data && !list.data.canCreate) { + return ( + + + Ask an admin of your organization to create it. + + + ); + } + + return ( + +
{ + event.preventDefault(); + void form.handleSubmit().catch(() => undefined); + }} + > + + + + + } + > + + + {(field) => { + const isInvalid = + field.state.meta.isTouched && !field.state.meta.isValid; + return ( + + Name + + field.handleChange(event.target.value) + } + placeholder="Sales" + value={field.state.value} + /> + {isInvalid ? ( + + ) : null} + + ); + }} + + + {(field) => { + const isInvalid = + field.state.meta.isTouched && !field.state.meta.isValid; + return ( + + Description + + Say what the team is for. You can leave this empty. + +