@collective-intelligence/extensions-sdk-backend 0.2.7 → 0.2.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +4 -0
- package/README.md +7 -0
- package/dist/effect/datasets/provider-implementations.d.ts +14 -2
- package/dist/effect.js +1 -1
- package/docs/effect.md +3 -0
- package/docs/guide/ai/index.md +349 -0
- package/docs/guide/data/connectors.md +204 -0
- package/docs/guide/data/datasets.md +156 -0
- package/docs/guide/data/knowledge.md +211 -0
- package/docs/guide/develop/extensions.md +208 -0
- package/docs/guide/develop/external-apps.md +245 -0
- package/docs/guide/develop/sdks.md +233 -0
- package/docs/guide/index.md +78 -0
- package/docs/guide/platform/access.md +244 -0
- package/docs/guide/platform/architecture.md +142 -0
- package/docs/guide/platform/entrypoints.md +236 -0
- package/docs/guide/scenarios/index.md +107 -0
- package/docs/guide/template/index.md +276 -0
- package/docs/guide/template/state-machines.md +294 -0
- package/package.json +4 -4
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
# SDKs
|
|
2
|
+
|
|
3
|
+
Which @collective-intelligence package to import, from which subpath, with which Effect setup and which versions.
|
|
4
|
+
|
|
5
|
+
The SDK family splits by where your code runs. Code that you install into CI as part of a package uses the `@collective-intelligence/extensions-sdk*` packages. Code that you host yourself, such as a Next.js web app and its BFF, uses the `@collective-intelligence/external-apps-*` packages.
|
|
6
|
+
|
|
7
|
+
The template keeps the families apart. Package code imports only `extensions-sdk*` and `ui-react`, browser code imports the client SDK, and confidential server code imports the server SDK.
|
|
8
|
+
|
|
9
|
+
## Where your code runs
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart LR
|
|
13
|
+
subgraph pkg["Package: apps/extensions and ./ci subpaths"]
|
|
14
|
+
decl["Declarations<br/>extensions-sdk"]
|
|
15
|
+
impl["Tool and connector classes<br/>extensions-sdk-backend"]
|
|
16
|
+
widget["Studio widgets<br/>extensions-sdk-frontend(-react)"]
|
|
17
|
+
end
|
|
18
|
+
subgraph ci["Inside CI"]
|
|
19
|
+
backend["CI backend"]
|
|
20
|
+
hosts["Studio and Dashboard"]
|
|
21
|
+
end
|
|
22
|
+
subgraph app["Your app: apps/web"]
|
|
23
|
+
browser["Browser code<br/>external-apps-client-sdk(-react)"]
|
|
24
|
+
server["Server code and BFF<br/>external-apps-server-sdk"]
|
|
25
|
+
end
|
|
26
|
+
cli["ci CLI"]
|
|
27
|
+
pkg --> cli
|
|
28
|
+
cli -->|"ci deploy"| backend
|
|
29
|
+
impl -.->|"runs in"| backend
|
|
30
|
+
widget -.->|"renders in"| hosts
|
|
31
|
+
browser -->|"same-origin proxy"| server
|
|
32
|
+
server -->|"confidential credentials"| backend
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
In the template, the left side is `apps/extensions` plus the `./ci` subpath of each entity and feature package. The CLI builds that code into a release and installs it into your Organization. After install, CI runs the backend classes and Studio renders the widgets, so this code never runs in your app.
|
|
36
|
+
|
|
37
|
+
The right side is `apps/web`. Its browser code talks to its own server through a same-origin proxy, and the server calls CI with the application's confidential credentials. A browser can also call CI directly through the client SDK; in that case your app does not need the server SDK.
|
|
38
|
+
|
|
39
|
+
## The packages
|
|
40
|
+
|
|
41
|
+
| Package | Runs where | Main subpaths | Use it for |
|
|
42
|
+
| --------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
43
|
+
| `@collective-intelligence/extensions-sdk` | Package build | `.`, `/effect` (empty) | Declare the package and its components with `declarePackage` and the other `declare*` functions |
|
|
44
|
+
| `@collective-intelligence/extensions-sdk-backend` | Inside CI, backend | `.`, `/effect` | Implement the code that tools, connectors and dataset providers run |
|
|
45
|
+
| `@collective-intelligence/extensions-sdk-frontend` | Inside CI, Studio and Dashboard | `.`, `/effect` (empty) | Declare the frontend catalog that a Host loads through `loadFrontendCatalog` |
|
|
46
|
+
| `@collective-intelligence/extensions-sdk-frontend-react` | Inside CI, Studio and Dashboard | `/studio`, `/studio-api`, `/dashboard`, `/workflow`, `/ui-react`, `/effect` | Write the React code of a Studio widget or Dashboard contribution |
|
|
47
|
+
| `@collective-intelligence/external-apps-client-sdk` | Your app, browser | `.`, `/resources`, `/effect` | Sign users in with CI and call CI operations without React |
|
|
48
|
+
| `@collective-intelligence/external-apps-client-sdk-react` | Your app, browser | `.`, `/resources`, `/effect` | Providers and entity hooks that read and write CI records |
|
|
49
|
+
| `@collective-intelligence/external-apps-server-sdk` | Your app, server only | `.`, `/auth/federated`, `/effect`, `/next`, `/admin` | BFF routes, sign-in and confidential calls to CI |
|
|
50
|
+
| `@collective-intelligence/ui-react` | Both sides | `/ui`, `/resources`, `/icons`, `/hooks`, `/tokens/theme` | CI design-system components that take display-ready props |
|
|
51
|
+
| `@collective-intelligence/cli` | Your machine or pipeline | `ci` binary | Sign in, build and deploy packages, enroll an app |
|
|
52
|
+
| `@collective-intelligence/lint` | Development | `recommended` | Oxlint rules that keep the solution layout and Effect imports correct |
|
|
53
|
+
| `@collective-intelligence/schema-codegen` | Development | `.` | Generate TypeScript, Zod or Effect Schema source from package schemas |
|
|
54
|
+
|
|
55
|
+
You rarely import `schema-codegen` yourself, because `ci package codegen --target zod|effect|types` calls it for you. Generated schemas describe the wire shape only, and the CI backend still validates every payload.
|
|
56
|
+
|
|
57
|
+
The `ci` binary runs on Bun. Install it globally and keep it current with `ci upgrade`:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm install -g @collective-intelligence/cli
|
|
61
|
+
ci login <api-url> --organization <organization-id>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`@collective-intelligence/lint` needs `oxlint` 1.82.0 or later:
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
import { recommended } from "@collective-intelligence/lint"
|
|
68
|
+
import { defineConfig } from "oxlint"
|
|
69
|
+
export default defineConfig({ extends: [recommended] })
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Code that runs inside CI
|
|
73
|
+
|
|
74
|
+
### Declarations with `extensions-sdk`
|
|
75
|
+
|
|
76
|
+
`extensions-sdk` is the framework-neutral authoring contract. Its root loads no Effect, React, Zod, database or HTTP code, and it is the only entrypoint you import; do not deep-import its internal folders. Every declaration has the same shape, `declareX({ manifest, presentation, definition, implementation })`. `manifest` holds `{ fqn, version }`, `presentation` holds catalog metadata such as the display name, `definition` holds the serializable data for that kind, and `implementation` is a class constructor that only executable kinds such as tools take. [Extensions](extensions.md) lists what a package can declare.
|
|
77
|
+
|
|
78
|
+
### Backend code with `extensions-sdk-backend`
|
|
79
|
+
|
|
80
|
+
This package holds the executable base classes, such as `PackageTool` and the connector and dataset provider classes, and the runtime context they receive. The root returns plain values and `PromiseLike` results, so it works without Effect:
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import {
|
|
84
|
+
PackageTool,
|
|
85
|
+
type PackageRuntimeContext
|
|
86
|
+
} from "@collective-intelligence/extensions-sdk-backend"
|
|
87
|
+
|
|
88
|
+
export class EchoTool extends PackageTool<{ text: string }, string> {
|
|
89
|
+
execute(
|
|
90
|
+
input: { text: string },
|
|
91
|
+
_context: PackageRuntimeContext
|
|
92
|
+
): PromiseLike<string> {
|
|
93
|
+
return Promise.resolve(input.text)
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
> **Warning:** One Worker serves every Organization that invokes the same package release,
|
|
99
|
+
> and several calls can run at the same time. Read the Organization,
|
|
100
|
+
> capabilities and configuration only from the per-call `context`, and never
|
|
101
|
+
> keep tenant data in module-level variables.
|
|
102
|
+
> [Extensions](extensions.md) describes the other runtime rules.
|
|
103
|
+
|
|
104
|
+
### Studio widgets with `extensions-sdk-frontend` and `extensions-sdk-frontend-react`
|
|
105
|
+
|
|
106
|
+
`extensions-sdk-frontend` declares the catalog. Every Studio or Dashboard contribution exports a function named `loadFrontendCatalog`, and every `declareFrontendComponent` needs a `load: () => import("./x")` callback, because a bundled Host cannot import a renderer by module name.
|
|
107
|
+
|
|
108
|
+
`extensions-sdk-frontend-react` holds the React side. Studio passes a widget a `context` prop with `appId`, `organizationId`, `pageId` and `viewId`. In the builder preview, or before the app is published, `context` is `null`, so hide API calls until it has a value. The template's Lead score card imports from these subpaths:
|
|
109
|
+
|
|
110
|
+
```tsx
|
|
111
|
+
import { studioViewScope } from "@collective-intelligence/extensions-sdk-frontend-react/studio"
|
|
112
|
+
import { studioViewDataSearchOptions } from "@collective-intelligence/extensions-sdk-frontend-react/studio-api"
|
|
113
|
+
import { Card, Progress } from "@collective-intelligence/ui-react/ui"
|
|
114
|
+
import { useQuery } from "@tanstack/react-query"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`/studio-api` is a generated client for the backend operations a widget may call. Studio binds it to the signed-in user's session, so the widget configures no credentials and every request runs with that user's own permissions. Inside Studio and Dashboard the Host provides `react`, `react-dom` and `ui-react`. The CLI keeps `ui-react` external at build, so a widget shares the Host's copy.
|
|
118
|
+
|
|
119
|
+
## Code that runs in your app
|
|
120
|
+
|
|
121
|
+
`external-apps-client-sdk` is browser-safe and React-free. It handles federated login with `createFederatedAuth` (OAuth authorization code with PKCE) and typed CI operations with `createClient(...).forOrganization(id)`. It holds no confidential credentials. Its `/resources` subpath exports `ResourceDefinition`, the portable contract that both the browser hooks and the BFF read. The template keeps the Lead contract in `@acme/lead/domain`.
|
|
122
|
+
|
|
123
|
+
`external-apps-client-sdk-react` adds `CollectiveIntelligenceProvider`, `CollectiveIntelligenceLoginProvider` and the entity hooks on `/resources`: `useEntityList`, `useEntityRecord`, `useEntityCreate`, `useEntityUpdate` and `useEntityDelete`. A write hook reports `conflict`, `rejected` and `uncertain` as well as `idle`, `pending` and `success`, and `resubmit()` repeats the exact same action when the user asks for it. Install its peers in your app: `react`, `react-dom`, `@tanstack/react-query`, `xstate`, `effect` and `@collective-intelligence/ui-react`.
|
|
124
|
+
|
|
125
|
+
The template's own pages use the template's shadcn/ui package, `@acme/ui`. `ui-react` appears in the Studio widget and in SDK toasts.
|
|
126
|
+
|
|
127
|
+
### Server SDK subpaths a demo uses
|
|
128
|
+
|
|
129
|
+
`external-apps-server-sdk` runs only on your server, because it holds the application's client secret. Each framework peer loads only from its own subpath: `/next` loads `next`, while `/effect` loads no `next`, `pg` or `drizzle-orm`. Administrative APIs exist only on `/admin` and never reach the browser proxy. A demo uses four subpaths:
|
|
130
|
+
|
|
131
|
+
| Subpath | What you get |
|
|
132
|
+
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
133
|
+
| `.` | `createServerClient`, for calls from your server to CI with the application's credentials |
|
|
134
|
+
| `/auth/federated` | CI sign-in, the sealed session, token verification and `readApplicationEnrollment` |
|
|
135
|
+
| `/effect` | `layerServerClient` and the Effect `ServerClient` service |
|
|
136
|
+
| `/next` | `createExternalApplicationBffNextHandlers`, `createFixedWorkflowRoute`, `nextInvalidate`, `createRealtimeRevalidateHandler` |
|
|
137
|
+
|
|
138
|
+
The template mounts its whole BFF with one call:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
handlers: createExternalApplicationBffNextHandlers({
|
|
142
|
+
auth: ci.auth,
|
|
143
|
+
capabilities: { basePath: "/api", tenantUrl: ci.tenantUrl },
|
|
144
|
+
ciResources: {
|
|
145
|
+
bindings: [{ definition: leadContract, schemaFqn: leadSchemaFqn }, ...],
|
|
146
|
+
invalidate: nextInvalidate,
|
|
147
|
+
organizationId: ci.organizationId,
|
|
148
|
+
tenantUrl: ci.tenantUrl,
|
|
149
|
+
},
|
|
150
|
+
publicOrigin: ci.publicOrigin,
|
|
151
|
+
realtime: { ... },
|
|
152
|
+
})
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
[External apps](external-apps.md) covers sign-in, the BFF and fixed workflow routes in detail.
|
|
156
|
+
|
|
157
|
+
## Effect
|
|
158
|
+
|
|
159
|
+
`effect` `^4.1.0` is a required peer of `extensions-sdk`, `extensions-sdk-backend`, both frontend extension packages and the three `external-apps-*` packages. The SDKs do not bundle it, so install it in your app and keep one version across the workspace.
|
|
160
|
+
|
|
161
|
+
Effect APIs always come from a `/effect` subpath, and the lint rule `effect-subpath` reports an Effect import from anywhere else.
|
|
162
|
+
|
|
163
|
+
| Package | What `/effect` holds |
|
|
164
|
+
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
165
|
+
| `extensions-sdk`, `extensions-sdk-frontend` | Nothing. These packages have no I/O client, so they need no Effect service. |
|
|
166
|
+
| `extensions-sdk-backend` | `effectSchema` and the Effect Dataset Provider ports |
|
|
167
|
+
| `extensions-sdk-frontend-react` | The `StudioApi` service, `fromEffect`, `EffectRuntimeProvider`, `useEffectRuntime` and `QueryCache` for writes in a widget |
|
|
168
|
+
| `external-apps-client-sdk-react` | The Effect bridge for XState machines |
|
|
169
|
+
| `external-apps-server-sdk` | `layerServerClient` and `ServerClient`; `/effect/next` adds the Next layer and `/effect/node-postgres` adds `layerNodePostgres` |
|
|
170
|
+
|
|
171
|
+
Tool schemas use Effect Schema through `effectSchema`. Effect's static types cannot tell whether a schema encodes safely, so `effectSchema(schema)` makes a decoder by default, and an output schema must opt in with `{ codec: true }`:
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
input: effectSchema(leadScoreInputSchema),
|
|
175
|
+
output: effectSchema(leadScoreSchema, { codec: true }),
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Versions
|
|
179
|
+
|
|
180
|
+
Each package has its own version on npm, and the family has no lockstep release. `extensions-sdk` 0.2.6 and `ui-react` 0.2.6 do not come from the same release. The public SDKs depend on each other at exact versions. Install the set that the template pins, and when you upgrade, take the template's new pins.
|
|
181
|
+
|
|
182
|
+
At the time of writing, the template catalog pins these versions:
|
|
183
|
+
|
|
184
|
+
| Package | Version |
|
|
185
|
+
| -------------------------------- | ------- |
|
|
186
|
+
| `extensions-sdk` | 0.2.6 |
|
|
187
|
+
| `extensions-sdk-backend` | 0.2.7 |
|
|
188
|
+
| `extensions-sdk-frontend` | 0.2.6 |
|
|
189
|
+
| `extensions-sdk-frontend-react` | 0.2.12 |
|
|
190
|
+
| `external-apps-client-sdk` | 0.2.16 |
|
|
191
|
+
| `external-apps-client-sdk-react` | 0.2.25 |
|
|
192
|
+
| `external-apps-server-sdk` | 0.2.21 |
|
|
193
|
+
| `lint` | 0.2.4 |
|
|
194
|
+
| `ui-react` | 0.2.3 |
|
|
195
|
+
| `effect` | 4.1.0 |
|
|
196
|
+
|
|
197
|
+
> **Note:** The release workflow bumps the template pins after each npm release. Copy the
|
|
198
|
+
> catalog from the current template instead of this table.
|
|
199
|
+
|
|
200
|
+
Some names from older examples no longer exist. An old server SDK subpath fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`, and the lint rule `effect-subpath` reports it.
|
|
201
|
+
|
|
202
|
+
| Old import | Use instead |
|
|
203
|
+
| -------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
204
|
+
| `@collective-intelligence/extensions-sdk-backend-effect` | `@collective-intelligence/extensions-sdk-backend/effect`, same export names |
|
|
205
|
+
| `@collective-intelligence/extensions-sdk-backend-zod` | Effect Schema through `effectSchema` from `extensions-sdk-backend/effect` |
|
|
206
|
+
| `external-apps-server-sdk/runtime/effect` | `external-apps-server-sdk/effect` |
|
|
207
|
+
| `external-apps-server-sdk/persistence/drizzle/effect` | `external-apps-server-sdk/effect` plus `/effect/node-postgres` |
|
|
208
|
+
| `external-apps-server-sdk/runtime/next` | `external-apps-server-sdk/next` |
|
|
209
|
+
|
|
210
|
+
The two removed packages stopped at version 0.2.0, and npm marks them deprecated.
|
|
211
|
+
|
|
212
|
+
## Pick a package
|
|
213
|
+
|
|
214
|
+
| I want to | Use |
|
|
215
|
+
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
216
|
+
| Declare a schema, tool, Agent, workflow, Studio app, group or Access Profile | `extensions-sdk` |
|
|
217
|
+
| Write the code a tool or connector runs inside CI | `extensions-sdk-backend`, with `/effect` for Effect schemas |
|
|
218
|
+
| Render a custom widget in Studio | `extensions-sdk-frontend` for the catalog and `extensions-sdk-frontend-react` (`/studio`, `/studio-api`) |
|
|
219
|
+
| Sign users in with CI and proxy record reads and writes from a Next.js server | `external-apps-server-sdk` (`/auth/federated`, `/next`) |
|
|
220
|
+
| Call CI from server code with the application's credentials | `external-apps-server-sdk` root or `/effect` |
|
|
221
|
+
| Show and edit CI records on a browser page | `external-apps-client-sdk-react` (`/resources`) |
|
|
222
|
+
| Call CI from a browser without React | `external-apps-client-sdk` |
|
|
223
|
+
| Reuse CI design-system components | `ui-react` |
|
|
224
|
+
| Build, deploy, enroll an app or sign in | `cli` |
|
|
225
|
+
| Generate types from package schemas | `ci package codegen`, which wraps `schema-codegen` |
|
|
226
|
+
| Enforce the solution layout | `lint` |
|
|
227
|
+
|
|
228
|
+
## Related pages
|
|
229
|
+
|
|
230
|
+
- [Extensions](extensions.md)
|
|
231
|
+
- [External apps](external-apps.md)
|
|
232
|
+
- [Template](../template/index.md)
|
|
233
|
+
- [Access](../platform/access.md)
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Start here
|
|
2
|
+
|
|
3
|
+
A guide for developers who build customer demos on the Collective Intelligence platform.
|
|
4
|
+
|
|
5
|
+
This guide is for developers who build customer demos on Collective Intelligence (CI). Each demo starts as a new repository generated from the `next-effect-app` solution template, and it ends as a web app that runs against a CI Organization. The pages explain what the platform offers, which parts a demo needs, and how the template puts them together.
|
|
6
|
+
|
|
7
|
+
## How a demo fits on the platform
|
|
8
|
+
|
|
9
|
+
A demo has two halves that you deploy in different places. The extension package in `apps/extensions` is installed inside CI, where it declares the data, access rules and AI parts that the demo needs. The web app in `apps/web` runs outside CI, and its server calls CI on behalf of the signed-in user.
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart LR
|
|
13
|
+
subgraph repo[Demo repository]
|
|
14
|
+
ext[apps/extensions]
|
|
15
|
+
web[apps/web]
|
|
16
|
+
end
|
|
17
|
+
subgraph ci[CI Organization]
|
|
18
|
+
pkg[Installed package]
|
|
19
|
+
api[CI API]
|
|
20
|
+
end
|
|
21
|
+
ext -- ci deploy --> pkg
|
|
22
|
+
browser[Browser] --> web
|
|
23
|
+
web -- server calls with the user's token --> api
|
|
24
|
+
pkg -. declares schemas, access and AI .-> api
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## From template to running demo
|
|
28
|
+
|
|
29
|
+
1. Generate a new repository from `next-effect-app` and rename the `@acme` packages. [The solution template](template/index.md) explains the layout you get.
|
|
30
|
+
2. Choose the primitives for the scenario. [Choosing primitives](scenarios/index.md) maps common demo scenarios to the parts that fit them.
|
|
31
|
+
3. Declare entities, access and AI parts in the packages' `ci/` folders. The [Data](data/knowledge.md), [AI](ai/index.md) and [Grants and permissions](platform/access.md) pages describe each declaration.
|
|
32
|
+
4. Build the screens and server routes of the web app with the [SDKs](develop/sdks.md), following the patterns in [External apps](develop/external-apps.md).
|
|
33
|
+
5. Deploy the package to an Organization with `ci deploy`, as [Extensions](develop/extensions.md) describes, and point the web app at that Organization.
|
|
34
|
+
|
|
35
|
+
## Sections
|
|
36
|
+
|
|
37
|
+
- [Platform](platform/architecture.md): What CI is made of, how people and apps enter it, and how access works.
|
|
38
|
+
- [Data](data/knowledge.md): Where demo data lives: Knowledge, datasets and connectors.
|
|
39
|
+
- [AI](ai/index.md): Tools, Skills, Agents and workflows, and how they combine.
|
|
40
|
+
- [Build](develop/sdks.md): The SDKs, extension packages and external apps you write.
|
|
41
|
+
- [Template](template/index.md): The layout of `next-effect-app` and its state machine approach.
|
|
42
|
+
- [Scenarios](scenarios/index.md): Criteria for picking the primitives that fit a demo.
|
|
43
|
+
|
|
44
|
+
## Where to begin
|
|
45
|
+
|
|
46
|
+
If you are starting a new demo, read [Platform architecture](platform/architecture.md) first, then [The solution template](template/index.md), and use [Choosing primitives](scenarios/index.md) to plan the scenario. If you are adding a feature to a demo that already runs, go straight to the page for that part: data questions belong in Data, model and automation questions in AI, and code questions in Build.
|
|
47
|
+
|
|
48
|
+
## For agents
|
|
49
|
+
|
|
50
|
+
Agents can read this guide without a browser. `/llms.txt` lists every page with a link to its Markdown, `/llms-full.txt` returns the whole guide as one file, and each page has a Copy Markdown button and an Open menu for chat assistants. Search answers JSON at `/api/search?query=<terms>`.
|
|
51
|
+
|
|
52
|
+
The same guide ships inside the SDK packages. Every `@collective-intelligence/` SDK that has an `AGENTS.md` also has the guide under `docs/guide/`, so an agent that works in a demo repository finds it in `node_modules` next to the code it calls. To read the SDK source, clone the private mirror with `opensrc`:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
GITHUB_TOKEN=$(gh auth token) opensrc path collective-intelligence-solutions/sdks
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Pages
|
|
59
|
+
|
|
60
|
+
- Platform
|
|
61
|
+
- [Platform architecture](platform/architecture.md): The parts of Collective Intelligence, the three integration models, and how a demo package moves from build to install.
|
|
62
|
+
- [Entrypoints](platform/entrypoints.md): The ways people, apps and agents enter CI at runtime, and the package subpaths that demo code imports.
|
|
63
|
+
- [Grants and permissions](platform/access.md): How CI decides what a user, a Group, an app or an API key may do, and how to change it in the template.
|
|
64
|
+
- Data
|
|
65
|
+
- [Knowledge](data/knowledge.md): Declare schemas, store typed records, query them, and read and watch them from a demo app.
|
|
66
|
+
- [Datasets](data/datasets.md): Query typed tables of measurements, events and warehouse data, and control who can read them.
|
|
67
|
+
- [Connectors](data/connectors.md): Connect outside systems, map their fields to Knowledge schemas, and run and watch imports.
|
|
68
|
+
- AI
|
|
69
|
+
- [AI primitives](ai/index.md): Tools, Skills, Agents, workflows and Studio chat, how they compose, and how audiences, approvals, models, runs and timeouts behave.
|
|
70
|
+
- Build
|
|
71
|
+
- [SDKs](develop/sdks.md): Which @collective-intelligence package to import, from which subpath, with which Effect setup and which versions.
|
|
72
|
+
- [Extensions](develop/extensions.md): What a package declares, how the template wires it, how to deploy it with ci deploy, and the rules its code runs under.
|
|
73
|
+
- [External apps](develop/external-apps.md): Sign users in with CI, read and write their data through a BFF, cache shared reads and stay live with Realtime.
|
|
74
|
+
- Template
|
|
75
|
+
- [The solution template](template/index.md): What you get from next-effect-app, where each piece of code goes, and how to take a new demo from local dev to an installed package.
|
|
76
|
+
- [State machines](template/state-machines.md): How next-effect-app models UI flows as XState machines with Effect actors, keeps server data in the QueryCache, resends uncertain writes safely, and checks hard flows with Models.
|
|
77
|
+
- Scenarios
|
|
78
|
+
- [Choosing primitives](scenarios/index.md): Questions, criteria and scenario patterns for picking the CI primitives a demo needs.
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Grants and permissions
|
|
2
|
+
|
|
3
|
+
How CI decides what a user, a Group, an app or an API key may do, and how to change it in the template.
|
|
4
|
+
|
|
5
|
+
CI uses one access model for people, Groups, apps, service principals and API keys. Capabilities name the operations, Access Profiles bundle capabilities, Access Grants give a profile to someone, and Knowledge Data Policies decide which records a capability opens. This model replaced the older organization roles, app roles, API key scopes and OAuth scopes. The Dashboard still labels an Access Profile as "Role", so read that word as "profile" wherever you meet it.
|
|
6
|
+
|
|
7
|
+
## The model in one diagram
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart LR
|
|
11
|
+
P["Principal<br/>user, Group, service principal,<br/>app server, app visitors"] --> G[Access Grant]
|
|
12
|
+
G --> AP[Access Profile]
|
|
13
|
+
AP --> C[Capabilities]
|
|
14
|
+
MP[Max Privileges] -. caps app tokens and API keys .-> C
|
|
15
|
+
C --> DP[Knowledge Data Policy]
|
|
16
|
+
DP --> R[Records the caller may read or write]
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
A grant gives exactly one profile to exactly one recipient. The profile holds capabilities, and a Knowledge Data Policy turns a capability into rows of one schema. Max Privileges never give anything: they cut what an app's user tokens or an API key may use, whatever the grants say.
|
|
20
|
+
|
|
21
|
+
| Term | What it is | Who declares it |
|
|
22
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
23
|
+
| Capability | An operation CI authorizes, with a stable `code`. A Switch is off or on. A Read/Manage capability is off, `read` or `manage`, and `manage` includes `read`. Capabilities form a tree, and holding a node gives every node below it, including nodes a later release adds. | The core and packages |
|
|
24
|
+
| Access Profile | A set of capabilities for one audience: `user`, `server` or `anonymous`. | The core (six built-in, read-only profiles) and packages |
|
|
25
|
+
| Access Grant | One profile given to one recipient. | Packages, or at runtime through the Dashboard, invitations, SSO and the server SDK |
|
|
26
|
+
| Max Privileges | The most an app's user tokens or an API key may use. | Packages |
|
|
27
|
+
| Knowledge Data Policy | A rule on one schema and one operation (`read` or `write`): a required capability, an optional `where`, and the fields it lets the caller read or write. | The core and packages only. Nobody edits a policy at runtime. |
|
|
28
|
+
| Resource Audience | Who an agent, Skill, tool, workflow or Studio app is offered to. Entries name users, Groups, profile holders, apps, the whole Organization or anonymous visitors. | Packages |
|
|
29
|
+
|
|
30
|
+
## How CI decides
|
|
31
|
+
|
|
32
|
+
Every grant only allows. No grant and no audience entry can deny, so a policy that must hide some records does it with a `where` clause. CI also checks each grant alone, for reads, updates and read masks. If one grant holds the capability and a second grant holds the right perimeter, the two halves never combine into one permission.
|
|
33
|
+
|
|
34
|
+
Through an app, the user's effective access is the union of their grants, each checked alone, cut down to the app's Max Privileges. A Sales manager who is also an Organization admin still cannot do through the app what the Max Privileges leave out. Dashboard, Studio and MCP sessions are not cut this way.
|
|
35
|
+
|
|
36
|
+
A grant change takes effect within 60 seconds. Every Organization-scoped response carries an `x-access-version` header, and a client that sees the value change refetches its access snapshot from `GET /me/access`.
|
|
37
|
+
|
|
38
|
+
> **Note:** A Studio user reads no Knowledge record until something opens it: a package
|
|
39
|
+
> policy, the built-in knowledge reader profile or a custom profile. A schema
|
|
40
|
+
> without a policy shows its members nothing. In the same way, a resource with
|
|
41
|
+
> an empty audience is offered to nobody.
|
|
42
|
+
|
|
43
|
+
## Memberships carry no role
|
|
44
|
+
|
|
45
|
+
An Organization membership links one user to one Organization and has one kind, `member` or `guest`. An external app usually creates guests. The membership itself gives no access, because access comes only from grants. Every former role is now a grant of the matching built-in profile, such as `core.profiles.organization-admin` or `core.profiles.knowledge-reader`.
|
|
46
|
+
|
|
47
|
+
Groups are the usual way to hand out grants. A grant to a Group reaches its members. With `coverage: "inherited"` it also reaches members of every subgroup, and with `coverage: "direct"` it stops at the Group itself.
|
|
48
|
+
|
|
49
|
+
## Declared and runtime grants
|
|
50
|
+
|
|
51
|
+
A package can declare Groups, capabilities, profiles, policies, Max Privileges and grants, and the install creates them in the Organization. The template declares a Sales Group with a Sales managers subgroup. A subgroup has no handle of its own, so a grant names it by its FQN, which is the parent FQN, a dot and the subgroup key:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
export const salesGroupFqn = "acme.app.groups.sales"
|
|
55
|
+
const managersKey = "managers"
|
|
56
|
+
/** A subgroup has no handle: a grant names it by FQN. */
|
|
57
|
+
export const salesManagersGroupFqn = `${salesGroupFqn}.${managersKey}`
|
|
58
|
+
|
|
59
|
+
export const salesGroup = declareOrganizationGroup({
|
|
60
|
+
definition: {
|
|
61
|
+
lifecycle: { deployMode: "upsert", readonly: true },
|
|
62
|
+
subgroups: [
|
|
63
|
+
{
|
|
64
|
+
description: "Sales managers of the Acme CRM.",
|
|
65
|
+
displayName: "Sales managers",
|
|
66
|
+
key: managersKey
|
|
67
|
+
}
|
|
68
|
+
]
|
|
69
|
+
},
|
|
70
|
+
manifest: { fqn: salesGroupFqn, version: VERSION },
|
|
71
|
+
presentation: {
|
|
72
|
+
description: "Sales team of the Acme CRM.",
|
|
73
|
+
displayName: "Sales"
|
|
74
|
+
}
|
|
75
|
+
})
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The package declares the Groups but never fills them. After install, an administrator adds people to Sales or Sales managers.
|
|
79
|
+
|
|
80
|
+
The template grants the Sales rep profile to Sales and the Sales manager profile to Sales managers, both with `inherited` coverage. Managers are also members of Sales through the tree, so a manager holds both grants. The lifecycle of each grant decides who owns it after install. The Sales grant uses `deployMode: "init_only"` with `readonly: false`, so an administrator can revoke it and a package update does not write it again. The managers grant uses `upsert` with `readonly: true`, so the package keeps it in place.
|
|
81
|
+
|
|
82
|
+
Runtime grants come from the Dashboard, invitations, SSO defaults and the provisioning API. An app's server manages them through `ci.access` in the server SDK. `sync` makes the runtime grants under one namespace match the list exactly:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
await ci.access.grants.sync({
|
|
86
|
+
grants: [
|
|
87
|
+
{
|
|
88
|
+
fqn: "clinic.patients.p-1001",
|
|
89
|
+
grantee: { user: { email: "patient@example.test" } },
|
|
90
|
+
profile: "clinic.profiles.patient"
|
|
91
|
+
}
|
|
92
|
+
],
|
|
93
|
+
namespace: "clinic.patients",
|
|
94
|
+
organizationId
|
|
95
|
+
})
|
|
96
|
+
// result = { created, updated, deleted, unchanged }: Access Grant FQNs.
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The app's server acts only with the grants an administrator gave to it as `{ applicationServer }`. It creates and changes only its own guests, reads Groups without writing them, sends no invitations, and never touches a package-declared grant.
|
|
100
|
+
|
|
101
|
+
## Data policies narrow records
|
|
102
|
+
|
|
103
|
+
A capability opens a feature. A Knowledge Data Policy decides which records of one schema that capability reaches. The template generates two policies for each of its schemas: reading needs CRM `read`, and writing needs CRM `manage`.
|
|
104
|
+
|
|
105
|
+
```ts
|
|
106
|
+
declareAccessKnowledgeDataPolicy({
|
|
107
|
+
definition: {
|
|
108
|
+
capability: requires(capability, "manage"),
|
|
109
|
+
lifecycle: readonly,
|
|
110
|
+
operation: "write",
|
|
111
|
+
target,
|
|
112
|
+
},
|
|
113
|
+
manifest: { fqn: `acme.app.policies.${name}-write`, version: VERSION },
|
|
114
|
+
}),
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Several policies on the same schema and operation combine with OR. A `where` clause limits the rows, and `readableFields: { except: ["salary"] }` removes a field from the result. Read masks do not apply to search, embeddings or filters yet, so a masked value can still match a search. Each record the caller reads also carries `access.write`, which tells the UI whether this caller may change that record and lets a page hide the edit button row by row.
|
|
118
|
+
|
|
119
|
+
A profile can also declare Grant Axes, such as Company or Country, so that one grant reads "this profile, but only for Italy". The template uses no axes. See [Knowledge](../data/knowledge.md) for schemas, conditions and axes in policies.
|
|
120
|
+
|
|
121
|
+
## The app gate
|
|
122
|
+
|
|
123
|
+
Every external app has an app gate: a Switch capability at the root of the app's capability tree, with the app FQN as its code. CI accepts a user's token for the app only when one of the user's grants holds the gate, so a user with no such grant cannot sign in. Both template profiles hold it:
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
export const managerProfile = declareAccessProfile({
|
|
127
|
+
definition: {
|
|
128
|
+
audience: "user",
|
|
129
|
+
capabilities: [
|
|
130
|
+
allow(accessGate(acmeApplication)),
|
|
131
|
+
allow(core.platform.knowledge),
|
|
132
|
+
allow(core.platform.agents),
|
|
133
|
+
allow(core.platform.workflows),
|
|
134
|
+
allow(crmCapabilities, "manage")
|
|
135
|
+
],
|
|
136
|
+
lifecycle: readonly
|
|
137
|
+
},
|
|
138
|
+
manifest: { fqn: "acme.app.profiles.manager", version: VERSION },
|
|
139
|
+
presentation: { displayName: "Sales manager" }
|
|
140
|
+
})
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The Sales rep profile holds the same gate with `platform.knowledge`, `platform.agents` and CRM `read`. It leaves out `platform.workflows` and CRM `manage`.
|
|
144
|
+
|
|
145
|
+
The gate lets a user in. Max Privileges then limit what the app's user tokens may use, for every caller including tenant users:
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
export const applicationTokens = declareAccessMaxPrivileges({
|
|
149
|
+
definition: {
|
|
150
|
+
appliesTo: { applicationTokens: acmeApplication },
|
|
151
|
+
capabilities: [
|
|
152
|
+
allow(core.platform.knowledge),
|
|
153
|
+
allow(core.platform.agents),
|
|
154
|
+
allow(core.platform.workflows),
|
|
155
|
+
allow(crmCapabilities, "manage")
|
|
156
|
+
],
|
|
157
|
+
lifecycle: readonly
|
|
158
|
+
},
|
|
159
|
+
manifest: { fqn: "acme.app.max-privileges.user-tokens", version: VERSION }
|
|
160
|
+
})
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
> **Warning:** An app registered from the Dashboard or the CLI has no Max Privileges, so its
|
|
164
|
+
> user tokens can sign in and read no data at all. Declare the app in a package
|
|
165
|
+
> together with its Max Privileges when its tokens must read data.
|
|
166
|
+
|
|
167
|
+
Consent is a separate setting. `applicationConsent` (`inherit`, `ask` or `skip`) only decides whether the user sees an Allow and Deny panel. A user without a grant that holds the gate is refused under `skip` exactly as under `ask`. The [External apps](../develop/external-apps.md) page covers sign-in and consent in full.
|
|
168
|
+
|
|
169
|
+
## API keys and service principals
|
|
170
|
+
|
|
171
|
+
A service principal is a non-human identity, declared with `servicePrincipal({ fqn, groups, name, version })`. It holds only the grants that name it with `grantee: { servicePrincipal }`. The template's `convertLeadRunner` is a service principal with no Groups that the convert-lead workflow can run as.
|
|
172
|
+
|
|
173
|
+
An API key belongs to a service principal and is created with a Max Privileges template:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
ci api-keys upsert --principal <fqn> --name <name> --max-privileges <template-fqn>
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The template sets the ceiling, and the principal's grants decide what the key may do below it. A key without a template uses no capability, and no API key can manage API keys. CI shows the secret once.
|
|
180
|
+
|
|
181
|
+
> **Warning:** A run as a service principal asks no questions and decides no approvals. Tool
|
|
182
|
+
> approval gates do not stop it: CI approves unattended calls by default and
|
|
183
|
+
> records them without an actor. Plan for this before a demo drives an agent
|
|
184
|
+
> with an API key.
|
|
185
|
+
|
|
186
|
+
The template's server also reads Leads with the app's own credential (the Read Port on the [External apps](../develop/external-apps.md) page). The package declares no `{ applicationServer }` grant for it, so an administrator must give the app server read access to Leads after install.
|
|
187
|
+
|
|
188
|
+
## Hide in the UI, check on the server
|
|
189
|
+
|
|
190
|
+
The template checks every protected action three times, and no layer trusts the one above it:
|
|
191
|
+
|
|
192
|
+
```mermaid
|
|
193
|
+
flowchart LR
|
|
194
|
+
Page["Page<br/>holds hides the button"] --> Route["BFF route<br/>403 without the requirement"]
|
|
195
|
+
Route --> CI["CI<br/>grants, Max Privileges, policies<br/>for the run and each record"]
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
An Access Requirement is a serializable guard built from `requires`, `enters`, `allOf` and `anyOf`. A feature package exports the requirement of each operation, so the page and the route check the same value. On the server, `CiRuntime.access(cookie)` returns the app's slice of the user's capabilities, and `holds(slice, requirement)` checks one requirement against it. The browser SDK session holds no access data.
|
|
199
|
+
|
|
200
|
+
```tsx
|
|
201
|
+
const CrmLeaf = async () => {
|
|
202
|
+
const access = await readSessionAccess()
|
|
203
|
+
return <CrmWorkspace canConvert={holds(access, convertLeadRequirement)} />
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The leaf reads request cookies, so it sits inside `<Suspense>`. Without a session, or when CI is down, the access slice is `null` and no gated control appears. When the user's access changes during a session, CI reports it on the realtime stream and `RealtimeProviders` refreshes the route, so the button appears or disappears without a reload.
|
|
208
|
+
|
|
209
|
+
Dashboard feature flags such as `organization_onboarding`, `knowledge_setup` and `apps_setup` belong to the hiding layer only. They remove Dashboard entry points and leave capabilities and server checks unchanged.
|
|
210
|
+
|
|
211
|
+
## Worked example: Sales members can convert leads
|
|
212
|
+
|
|
213
|
+
The template's CRM page has a Convert action that starts the convert-lead workflow. Here is how to give it to every Sales member.
|
|
214
|
+
|
|
215
|
+
1. Check what the template does today. `convertLeadRequirement` is `{ mode: "on", requires: "platform.workflows" }`. Only the Sales manager profile allows `core.platform.workflows`, so today only members of Sales managers see Convert and can run it. A member who is only in Sales gets no button, and the BFF route answers 403.
|
|
216
|
+
2. Add `allow(core.platform.workflows)` to `repProfile` in the organization package. The app's Max Privileges already allow `platform.workflows`, so they need no change. Bump `VERSION`, then build, publish, promote and install the package.
|
|
217
|
+
3. Check the Lead write. The browser call is delegated, so the workflow runs as the signed-in user and not as `convertLeadRunner`. The run marks the Lead `converted: true`, and the Lead write policy requires CRM `manage`, which reps do not hold. The template lets only managers convert, so it never exercises this path. If CI checks that write against the user's policies, a rep also needs CRM `manage`, or a narrower write policy with `writableFields: ["converted"]`. Confirm it with one trial run before the demo.
|
|
218
|
+
4. Sign in as a user who is only in Sales. The CRM page now shows Convert, and `POST /api/leads/:id/convert` answers `{ runId }`. Run `POST /admin/access/explain` to see which grant gives `platform.workflows`. Allow up to 60 seconds after a grant change, or wait for the realtime access event to refresh the page.
|
|
219
|
+
|
|
220
|
+
For a one-off demo you can skip the package change. An administrator grants the Sales manager profile to a single user in the Dashboard, which creates a runtime grant. The package stays the source of truth for the Sales tree, and the next demo starts from the declared grants again.
|
|
221
|
+
|
|
222
|
+
## Debug and test access
|
|
223
|
+
|
|
224
|
+
To answer "why can or can't this user do this?", call `POST /admin/access/explain`. The same check is the `explain_access` MCP tool and `ci.access.explain` in the server SDK. `GET /admin/access/members/:userId/access` lists a member's effective access with the grant behind each capability.
|
|
225
|
+
|
|
226
|
+
When a user installed the package and still cannot sign in to the app, check three things in order. The user must be in Sales or Sales managers, the grant for that Group must hold the app gate, and an administrator must have rotated the app's client secret. Install does none of this. A package that declares grants also needs an install with a user's management token, because a system install fails with `installer_required`.
|
|
227
|
+
|
|
228
|
+
You can test policies and profiles without a running CI. `accessTest` from `@collective-intelligence/extensions-sdk-backend` loads your packages and answers questions as a given user:
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
const check = accessTest([orgPackage, hrPackage], { corePolicies, entities })
|
|
232
|
+
|
|
233
|
+
check.as({ user, grants }).canRead(schema, record)
|
|
234
|
+
check.as({ user, grants }).holds(requirement)
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
The same object offers `.read(...)` for the masked record, `.canUpdate(...)` and `check.conditionTests()` for the built-in condition tests.
|
|
238
|
+
|
|
239
|
+
## Related pages
|
|
240
|
+
|
|
241
|
+
- [External apps](../develop/external-apps.md)
|
|
242
|
+
- [Knowledge](../data/knowledge.md)
|
|
243
|
+
- [Extensions](../develop/extensions.md)
|
|
244
|
+
- [The template](../template/index.md)
|