@collective-intelligence/extensions-sdk 0.2.6 → 0.2.8

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.
@@ -0,0 +1,245 @@
1
+ # External apps
2
+
3
+ Sign users in with CI, read and write their data through a BFF, cache shared reads and stay live with Realtime.
4
+
5
+ An external app is an application that runs outside CI and talks to it. The template's `apps/web` is one: a Next.js app with its own routes and API, plus a server-side BFF (backend-for-frontend) that signs users in with CI and forwards their Lead and Opportunity calls.
6
+
7
+ Traffic between an app and CI can flow in two directions. Outbound, the browser calls the app's BFF and the BFF calls CI under `/application/v1/`, to proxy records, use CI capabilities and start workflows. Inbound, CI calls a Gateway that the app hosts, to reach the app's own resources, datasets and operations. The template is outbound only, and most demos need nothing more.
8
+
9
+ ## When a demo needs an external app
10
+
11
+ You need one when the demo has its own UI outside Studio and the Dashboard, or when CI must reach data and actions that live in the customer's system. Pick the SDK path by what each screen or action needs:
12
+
13
+ | The demo needs | Use |
14
+ | ---------------------------------------------------- | ------------------------------------------------------- |
15
+ | Data that differs per user | BFF resource proxy (`ciResources`) and the entity hooks |
16
+ | The same data for every user, rendered on the server | The Read Port with `"use cache"` |
17
+ | A business action with side effects in CI | A Fixed workflow route |
18
+ | CI reaching your data or actions | A Gateway |
19
+ | Your own logic with your own store | The app API under `/api/app` |
20
+
21
+ ## Declare the app
22
+
23
+ A package declares the app as an OAuth client with `declareExternalApplication`. The template's declaration, with a placeholder origin:
24
+
25
+ ```ts
26
+ export const acmeApplication = declareExternalApplication({
27
+ definition: {
28
+ allowedOrigins: ["https://app.example.com"],
29
+ applicationType: "confidential",
30
+ audience: "https://app.example.com",
31
+ lifecycle: { deployMode: "upsert", readonly: true },
32
+ postLogoutRedirectUris: ["https://app.example.com/signed-out"],
33
+ // No OAuth scopes: `access.ts` grants the app gate and caps the tokens.
34
+ redirectUris: ["https://app.example.com/api/auth/callback"],
35
+ },
36
+ manifest: { fqn: applicationFqn, version: VERSION },
37
+ ...
38
+ });
39
+ ```
40
+
41
+ The declaration has no `scopes` field. What a user may do through the app comes from grants that hold the app gate and from the Max Privileges declared for the app's user tokens, both described on [Grants and permissions](../platform/access.md).
42
+
43
+ `ci apps enroll --env-file apps/web/.env.local` writes the app's enrollment into an env file: `CI_ISSUER`, `CI_AUDIENCE`, `CI_APPLICATION_ID`, `CI_CLIENT_ID`, `CI_ORGANIZATION_ID`, `CI_SCOPES` and, for a confidential app, `CI_CLIENT_SECRET`. Server code reads them with `readApplicationEnrollment(process.env)` and never names them one by one. `ci apps env <application>` prints the same set later without the secret. The Application Id is the registration id (the `app_id` claim), and the Client Id is the OAuth `client_id`. They are different values, and every CLI output names both.
44
+
45
+ Next to the enrollment, the template reads `APP_ORIGIN` (the public HTTPS origin), `CI_TENANT_URL`, `SESSION_SECRETS` (comma-separated, current secret first, so you can rotate) and `NEXT_PUBLIC_APPLICATION_ID`, the only value the browser sees.
46
+
47
+ ## After install
48
+
49
+ Installing the package registers the app. Users can sign in and see data only after the first four steps below; the fifth gives refused users a readable page.
50
+
51
+ 1. Rotate the client secret. Install creates a confidential app with no secret, so an Organization administrator with `external_apps:manage` rotates one from the Dashboard ("Rotate secret") or with `POST /admin/organization/external-apps/{id}/credential/rotate`. CI shows the secret once.
52
+ 2. Run `ci apps enroll` to write the env file, including the new secret.
53
+ 3. Add users to the Group whose grant holds the app gate. In the template that is Sales or Sales managers. The package declares the Groups and leaves them empty.
54
+ 4. Give the app server read access to Leads. The template's Read Port reads with the app's own credential, and the package declares no grant for it.
55
+ 5. Set `errorPath` on the federated auth so that a refused sign-in lands on a page instead of a JSON answer. The callback reports `access_denied`, `authorization_failed`, `invalid_state`, `invalid_request`, `invalid_identity` or `user_auth_unavailable`.
56
+
57
+ ## Sessions
58
+
59
+ Each deployment picks one session mode:
60
+
61
+ | Mode | Who owns the login | Where the session lives |
62
+ | ------------------------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
63
+ | Local | The app, with Better Auth email and password. A local user is not a CI member and gets no CI access. | The app |
64
+ | Federated, sealed cookie | CI | An encrypted, signed cookie. The template uses this mode. |
65
+ | Federated, session store | CI | Rows in the app's database |
66
+
67
+ The whole sign-in setup of the template is one call:
68
+
69
+ ```ts
70
+ const auth = createFederatedAuth({
71
+ ...enrollment,
72
+ applicationOrigin: env.APP_ORIGIN,
73
+ session: { kind: "sealed_cookie", secrets: env.SESSION_SECRETS }
74
+ })
75
+ ```
76
+
77
+ `createFederatedAuth` handles the PKCE login, the callback, session reads and logout under `/api/auth`. Register `<origin>/api/auth/callback` with `ci apps redirect-uris add` and the origin with `ci apps origins add`. The session cookie is `__Host-ci-federated` with `Secure`, `HttpOnly` and `SameSite=Lax`, which is why `APP_ORIGIN` must use HTTPS. On a laptop without a TLS proxy, `allowLoopbackHttp: true` lets `http://localhost:3000` work with a cookie named `ci-federated` and no `Secure` flag. Keep that option off in production.
78
+
79
+ Access tokens always live 300 seconds. A confidential client that passes its `clientSecret` to `createFederatedAuth` renews them silently: when a token has 30 seconds or less left, the session lookup gets a new one first. The renewed token stays in process memory and the cookie is written once at sign-in, so a server restart only triggers another renewal. The session itself lasts `sessionTtlSeconds`, 86400 by default and at most 604800, and never longer than the user's CI session.
80
+
81
+ > **Warning:** If users are logged out after five minutes, the app is a public client. A
82
+ > public client gets no renewal credential, so the session ends when the first
83
+ > access token expires, whatever `sessionTtlSeconds` says.
84
+
85
+ A revoked grant reaches the app at the next renewal, so within 300 seconds. It reaches the app at once when a forwarded CI answer is a `401` or carries a changed `x-access-version`, which `auth.observeCiResponse` watches for. A user who signs in without a grant that holds the app gate does not bounce straight back with `access_denied`. CI first shows its own access-denied page with "Switch account" and "Back to the application".
86
+
87
+ > **Note:** Consent follows the app's `applicationConsent` (`inherit`, `ask` or `skip`),
88
+ > and `inherit` uses the Organization default. If the browser already has a CI
89
+ > session cookie, CI issues the code silently under both `ask` and `skip`, so a
90
+ > tester who is signed in to CI never sees the consent panel.
91
+
92
+ ## The BFF pattern
93
+
94
+ The browser never holds a CI token. It calls same-origin `/api/*` routes, and the app's server keeps the session and calls CI with the user's delegated token:
95
+
96
+ ```mermaid
97
+ sequenceDiagram
98
+ participant B as Browser
99
+ participant F as BFF (app server)
100
+ participant C as CI
101
+ B->>F: GET /api/... with the sealed session cookie
102
+ F->>F: Open session, check the Access Requirement
103
+ F->>C: GET /application/v1/... with the delegated token and x-organization-id
104
+ C->>C: Check grants, Max Privileges and policies per record
105
+ C-->>F: Records the user may see
106
+ F-->>B: JSON, no token
107
+ ```
108
+
109
+ `createExternalApplicationBffNextHandlers` mounts federated auth, the resource proxy, capability forwarding and Realtime in one call:
110
+
111
+ ```ts
112
+ handlers: createExternalApplicationBffNextHandlers({
113
+ auth: ci.auth,
114
+ capabilities: { basePath: "/api", tenantUrl: ci.tenantUrl },
115
+ ciResources: {
116
+ bindings: [
117
+ { definition: leadContract, schemaFqn: leadSchemaFqn },
118
+ { definition: opportunityContract, schemaFqn: opportunitySchemaFqn },
119
+ ],
120
+ invalidate: nextInvalidate,
121
+ organizationId: ci.organizationId,
122
+ tenantUrl: ci.tenantUrl,
123
+ },
124
+ publicOrigin: ci.publicOrigin,
125
+ realtime: { organizationId: ci.organizationId, revalidate: createRealtimeRevalidateHandler,
126
+ secrets: ci.sessionSecrets, tenantUrl: ci.tenantUrl },
127
+ }),
128
+ ```
129
+
130
+ Each `ciResources` binding mounts one resource proxy for an entity contract. The BFF checks a `read` and a `write` Access Requirement against the app's slice of the user's access, `core.platform.knowledge` for both by default, and CI then checks each record again. Capability forwarding covers `context`, `knowledge`, `agents`, `conversations`, `skills`, `workflows` and `runs/*`.
131
+
132
+ The template mounts three route files:
133
+
134
+ | Route | Handler |
135
+ | ------------------------------------- | ----------------------------------------------------------------------- |
136
+ | `app/api/[...path]/route.ts` | The CI BFF: auth, resources, Realtime ticket |
137
+ | `app/api/leads/[id]/convert/route.ts` | Convert a Lead through a Fixed workflow route |
138
+ | `app/api/app/[[...path]]/route.ts` | The app's own Effect `HttpApi`, with OpenAPI at `/api/app/openapi.json` |
139
+
140
+ A server call to CI uses one of three identities. A delegated call, the default, uses the signed-in user's token, and the template's convert route works this way. `runAsApplication` switches one call to the app's confidential credentials and needs an audit subject. A service-mode client (`createServerClient({ authentication: { mode: "service", credentials } })`) always uses the app's own credential and gets the same answer for every user, which is what the template's Read Port does.
141
+
142
+ ## Reads and writes through the SDK
143
+
144
+ In the browser, the entity hooks of `external-apps-client-sdk-react` read and write through the BFF. Writes are optimistic by default: every view shows the new value at once, and a refused write rolls back and calls `onWriteFailed`, which `ciWriteFailedToast()` from `ui-react` turns into a toast. Pass `optimistic: false` to a hook to opt out. A write in the `uncertain` state was sent without an answer, so CI may have saved it. `resubmit()` sends the same action with the same idempotency key, and a new `submit()` starts a new action.
145
+
146
+ File uploads skip the BFF. The BFF asks CI for an upload slot, the browser sends the bytes straight to storage, and the record write then references `{ attachment: { upload } }`.
147
+
148
+ A business action with side effects goes through a Fixed workflow route. The server owns the workflow target and the browser only sends input:
149
+
150
+ ```ts
151
+ const handle = createFixedWorkflowRoute<{ leadId: string }, { leadId: string }>({
152
+ ...options,
153
+ idempotencyKey: ({ leadId }) => `convert-lead:${leadId}`,
154
+ requirement: convertLeadRequirement,
155
+ resourceId: "leads",
156
+ validate: (body, { leadId }) => { ... },
157
+ });
158
+ ```
159
+
160
+ The route rejects any `workflowId` or `workflowFqn` in the browser input, checks the Access Requirement, stamps `x-organization-id` from the session and returns `{ runId }`. The template's tests prove each refusal: an injected `workflowId` gets 400, no session gets 401, a missing capability gets 403, and two clicks reuse the idempotency key `convert-lead:<id>`.
161
+
162
+ The workflow must have an External application trigger bound to the app and an audience that includes it (`audience: { applications: [application] }`). A delegated call runs the workflow as the signed-in user. A service-mode call has no user, so the run uses the workflow's run-as service principal. CI publishes a triggered workflow only when it names one, which is why the template ships `convertLeadRunner`.
163
+
164
+ A run returns its `runId` at once. The template's `convertLeadTask` posts the convert route, follows the run with `runs.follow({ runId })` until it ends (10 minutes by default), and then invalidates the entity reads so every view reloads.
165
+
166
+ ## Server cache and invalidation
167
+
168
+ The SDK ships no cached read. The app writes the `"use cache"` directive itself, and `cacheCiRead(client, { schema, id?, filter?, life? })` adds the cache tags and a lifetime (by default stale 60, revalidate 60 and expire 86400 seconds). The template's Read Port is the one place that uses it:
169
+
170
+ ```ts
171
+ const lead = async (id: string) => {
172
+ "use cache"
173
+ cacheCiRead(getRuntime().service, { id, schema: leadSchemaFqn })
174
+ return await uncached().lead(id)
175
+ }
176
+ ```
177
+
178
+ `cacheCiRead` only type-checks with a service-mode client, so a user-session client does not compile. A shared cache must never hold one user's view, and user-scoped reads stay in TanStack Query in the browser. For the same reason the Read Port ignores each user's visibility, so give it only data that every signed-in user may see.
179
+
180
+ Tags cover all CI reads, a schema, a list, one entity and one Realtime topic. A write expires the record's entity tag and the list tag, and leaves cached reads of other records alone. The cache learns about a change in one of three ways:
181
+
182
+ ```mermaid
183
+ flowchart LR
184
+ W1[Write through the BFF] --> N[nextInvalidate]
185
+ W2["Write elsewhere<br/>workflow, Studio, agent, other app"] --> RT[Realtime change in an open tab] --> RV[Revalidate route]
186
+ W3[Effect server write] --> L[CacheInvalidation.layerNext on the fiber]
187
+ N --> T[Entity, list and topic tags expire]
188
+ RV --> T
189
+ L --> T
190
+ ```
191
+
192
+ > **Warning:** An Effect `ServerClient` write without `CacheInvalidation` on its fiber
193
+ > expires nothing and logs no error. Providing `layerNext` into
194
+ > `layerServerClient` does not reach the writes; merge it into the runtime
195
+ > instead.
196
+
197
+ Next's built-in cache store is in memory, so an invalidation reaches only the instance that received it. Other instances serve old data until the lifetime ends. Configure a shared cache store if the demo runs on more than one instance.
198
+
199
+ ## Realtime
200
+
201
+ Realtime keeps open pages current without polling. The browser asks the BFF for a ticket with `POST /api/realtime/ticket`, the BFF gets it from CI with the user's delegated token, and the browser opens the event stream with that single-use ticket. The user's token never reaches the browser.
202
+
203
+ A topic is one entity schema, optionally filtered by one field: `{ schema, filter?: { field, eq } }`. Events carry ids only, and the page refetches. One connection per tab carries all of its topics. A `reset` event means the client missed too much and must refetch everything; the first open of a connection also resyncs once, so expect one extra refetch per page load. Pass `onReset`, or a change can be lost. `onAccessChanged` fires when the user's access changes.
204
+
205
+ When the BFF has `secrets`, each ticket answer includes a sealed topic grant, valid for 10 minutes and bound to the session. The revalidate route `POST /api/realtime/revalidate` accepts changes only on topics in that grant, which is how a change from Studio or a workflow expires the server cache. The client renews the ticket after 8 minutes.
206
+
207
+ To show this in a demo, open `/crm` in two windows and edit a Lead as a Sales manager in one of them. The other window updates without a reload, also when the change comes from Studio, an agent or the convert-lead workflow.
208
+
209
+ > **Warning:** Do not open the stream with a hand-written `EventSource`. It cannot send the
210
+ > `Authorization` and `X-Organization-Id` headers that CI needs, and the failure
211
+ > is silent: the connection opens and no event arrives. The SDK's Realtime
212
+ > client uses tickets instead.
213
+
214
+ ## Effect and NestJS flavors
215
+
216
+ Every SDK has a Promise facade at its root import and an Effect API at `/effect`. In the Effect API, CI errors are typed failures instead of `{ ok: false }` values. `effect` is a peer dependency, so the app holds one copy. In the template, the server SDK's `./next` entry is imported only in `apps/web/src/server`; packages use `./effect` and stay independent of the host.
217
+
218
+ | | Template | Effect demo | NestJS demo |
219
+ | --------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
220
+ | Direction | Outbound | Outbound and inbound | Inbound |
221
+ | UI and login | Next.js, federated sealed cookie | React client, federated session store; the same Lead views run over local SQL, CI through the server, or CI direct | None |
222
+ | Convert lead | A CI workflow | A Gateway operation that creates one Opportunity and marks the Lead converted, idempotent by `x-idempotency-key` | Not included |
223
+ | CI entry points | BFF routes | BFF and Gateway | One `Greetings` service behind an HTTP route, an operation binding and an AI SDK tool |
224
+
225
+ A Gateway lists exactly what CI may discover:
226
+
227
+ ```ts
228
+ const gateway = defineGateway({
229
+ id: "crm",
230
+ version: "1.0.0",
231
+ knowledge: [{ resource: leadResource, access: "read_write" }],
232
+ datasets: [leadPipeline],
233
+ operationDomains: [crmOperations]
234
+ })
235
+ ```
236
+
237
+ Adapters for Next, Web Fetch, Express and Nest serve the same gateway kernel. A gateway exposes remote resources and never creates CI schemas: an administrator connects them through a Knowledge connector and maps fields onto an Organization schema. In NestJS, `bindNestOperation` binds an existing service method without decorators, and the CI entry point does not inherit your HTTP guards, pipes or interceptors, so each entry point keeps its own checks. Start Nest with `NestFactory.create(AppModule, { bodyParser: false })` so the SDK parses bounded JSON, and keep a global prefix off the gateway's `/v1/*` routes.
238
+
239
+ ## Related pages
240
+
241
+ - [Grants and permissions](../platform/access.md)
242
+ - [SDKs](sdks.md)
243
+ - [Extensions](extensions.md)
244
+ - [The template](../template/index.md)
245
+ - [Knowledge](../data/knowledge.md)
@@ -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.