@collective-intelligence/extensions-sdk-backend 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.
- 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,208 @@
|
|
|
1
|
+
# Extensions
|
|
2
|
+
|
|
3
|
+
What a package declares, how the template wires it, how to deploy it with ci deploy, and the rules its code runs under.
|
|
4
|
+
|
|
5
|
+
A package is a TypeScript module whose default export is `declarePackage({ manifest, components, hostedContributions })`. The `ci` CLI builds that module into a release, which is one immutable published version of the package. An administrator then installs the release into one Organization, and the installation records which release that Organization runs.
|
|
6
|
+
|
|
7
|
+
The template's package declares the Lead and Opportunity schemas, the Sales group tree, the external application of the web app, Sales Access Profiles and grants, the Max Privileges of the application's tokens, the convert-lead workflow, the lead qualifier Agent with its Skill and tool, and the Sales desk Studio app. [SDKs](sdks.md) explains which `@collective-intelligence/*` package each part imports.
|
|
8
|
+
|
|
9
|
+
## What a package can declare
|
|
10
|
+
|
|
11
|
+
| Declaration | What it creates in the Organization |
|
|
12
|
+
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
13
|
+
| `declareDomain`, `declareKnowledgeEntitySchema` | A Knowledge domain and the schemas of its records |
|
|
14
|
+
| `declareTool`, `declareToolCollection` | Tools that Agents and workflows call, grouped in collections |
|
|
15
|
+
| `declareSkill`, `declareAgent` | Skills and the Agents that hold them |
|
|
16
|
+
| `declareWorkflow`, `declareWorkflowNode` | Workflows and custom workflow nodes |
|
|
17
|
+
| `declareStudioApp` | A Declared Studio App that CI creates and publishes on install |
|
|
18
|
+
| `declareStudioAppTemplate` | A starting point that a builder copies into a new Studio app |
|
|
19
|
+
| `declareStudioComponent` | A Studio component, such as a widget of category `widget` |
|
|
20
|
+
| `declareConnection`, `declareConnectionInstance` | Connections to outside systems and their configured instances |
|
|
21
|
+
| `declareKnowledgeConnector`, `declareKnowledgeConnectorInstance` | Knowledge connectors and configured connector instances |
|
|
22
|
+
| `declareDocumentCollection` | One connected document collection, such as a Microsoft 365 drive folder |
|
|
23
|
+
| Dataset parsers, providers and blueprints | The dataset building blocks of the package |
|
|
24
|
+
| `declareOrganizationGroup` | A group tree with subgroups, created empty |
|
|
25
|
+
| `declareAccessCapabilities`, `declareAccessProfile`, `declareAccessProfileGrant` | Capabilities, Access Profiles, and Access Grants of a profile to a group |
|
|
26
|
+
| `declareAccessMaxPrivileges` | The Max Privileges of the application's user tokens |
|
|
27
|
+
| `declareOrganizationSettings` | Identity, branding, authentication, locale and governance settings (at most one per package) |
|
|
28
|
+
| `declareExternalApplication` | The OAuth client of your web app, with origins and redirect URIs |
|
|
29
|
+
| Event listeners, notification channels, email providers, Organization SSO, Organization Instructions | The matching Organization features |
|
|
30
|
+
|
|
31
|
+
Executable kinds also take an `implementation` class from `@collective-intelligence/extensions-sdk-backend`. Domains, schemas, policies, collections and Studio apps carry no class.
|
|
32
|
+
|
|
33
|
+
| Declaration | Class method that CI calls |
|
|
34
|
+
| ---------------------------- | ------------------------------------------- |
|
|
35
|
+
| `declareTool` | `PackageTool.execute` |
|
|
36
|
+
| `declareConnection` | `PackageConnection.test` |
|
|
37
|
+
| `declareKnowledgeConnector` | `pull` and `push` |
|
|
38
|
+
| `declareWorkflowNode` | `execute` |
|
|
39
|
+
| `declareEventListener` | Selectors plus `normalizeWebhook` or `poll` |
|
|
40
|
+
| `declareNotificationChannel` | `deliver` |
|
|
41
|
+
|
|
42
|
+
A component refers to another component of the same package through the handle that its `declare*` call returned. For a built-in component or one from another package, pass the FQN string instead, for example `"builtin.core.knowledge.tools.query"`. TypeScript does not check these strings. Install resolves them and rolls the package back when one does not exist, and the SDK publishes no list of built-in FQNs, so the template pins its FQNs in a `bun test` that catches a typo before deploy.
|
|
43
|
+
|
|
44
|
+
A package that declares Agents or Skills needs an administrator to install it. A package can depend on another package by FQN only, for example `dependencies: [{ fqn: "com.acme.base" }]`, and each install picks the latest eligible release of the dependency by promotion order.
|
|
45
|
+
|
|
46
|
+
## How the template wires the package
|
|
47
|
+
|
|
48
|
+
```mermaid
|
|
49
|
+
flowchart TD
|
|
50
|
+
ext["apps/extensions (@acme/extensions)<br/>index.ts: declarePackage<br/>studio.ts: loadFrontendCatalog"]
|
|
51
|
+
org["@acme/organization<br/>package identity, VERSION, domain,<br/>Sales group, external application,<br/>access, Studio app, packageComponents"]
|
|
52
|
+
lead["@acme/lead/ci<br/>Lead schema"]
|
|
53
|
+
opp["@acme/opportunity/ci<br/>Opportunity schema"]
|
|
54
|
+
qual["@acme/lead-qualification/ci<br/>tool, Skill, Agent, widget"]
|
|
55
|
+
conv["@acme/lead-conversion/ci<br/>convert-lead workflow"]
|
|
56
|
+
ext --> org
|
|
57
|
+
org --> lead
|
|
58
|
+
org --> opp
|
|
59
|
+
org --> qual
|
|
60
|
+
org --> conv
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The template keeps its CI code in three layers. `apps/extensions` is the composition root. It imports `@acme/organization` and one FQN from a `./ci` subpath. `@acme/organization` holds the package identity and everything shared across features, and it lists `packageComponents` in deploy order. Each entity or feature package exports a factory from its `./ci` subpath, for example `leadQualificationComponents({ application, audience, version })`, which takes the organization handles and the package version and returns its components in deploy order. A lower layer never imports `@acme/organization`.
|
|
64
|
+
|
|
65
|
+
This is the whole package entry:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import { leadScoreCardContributionFqn } from "@acme/lead-qualification/ci"
|
|
69
|
+
import { packageComponents, packageManifest } from "@acme/organization"
|
|
70
|
+
import { declarePackage } from "@collective-intelligence/extensions-sdk"
|
|
71
|
+
import { declareFrontendCatalogContribution } from "@collective-intelligence/extensions-sdk-frontend"
|
|
72
|
+
|
|
73
|
+
export default declarePackage({
|
|
74
|
+
components: packageComponents,
|
|
75
|
+
hostedContributions: [
|
|
76
|
+
declareFrontendCatalogContribution({
|
|
77
|
+
compatibility: { react: "^19.0.0" },
|
|
78
|
+
fqn: leadScoreCardContributionFqn,
|
|
79
|
+
host: "studio",
|
|
80
|
+
load: async () => await import("./studio")
|
|
81
|
+
})
|
|
82
|
+
],
|
|
83
|
+
manifest: packageManifest
|
|
84
|
+
})
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`apps/extensions/src/studio.ts` contains one line, `export { loadFrontendCatalog } from "@acme/organization"`. `ci package build` ships every export of that module to the browser, so it exports only the catalog loader.
|
|
88
|
+
|
|
89
|
+
One entity package such as `@acme/lead` holds the CI schema in `./ci`, the BFF code in `./server` and the React views in `./views`. The lint rule `ci-solution/subpath-imports` keeps React out of the CI release: `domain/` imports no other subpath, `ci/` imports no `headless/` or `views/`, and `headless/` and `views/` import no `server/`.
|
|
90
|
+
|
|
91
|
+
The template names components `acme.app.<kind>.<name>`, for example `acme.app.tools.lead-score` or `acme.app.workflows.convert-lead`, and the package itself is `acme.app.knowledge`. Each `./ci` subpath exports its FQN constants, and other code imports the constant instead of typing the string again.
|
|
92
|
+
|
|
93
|
+
A widget needs two declarations. On the backend side, `declareStudioComponent` with `category: "widget"`, a `propsSchema` and a `sourceRef` goes into `components`. On the frontend side, `declareFrontendComponent` with a `load` callback and a `studio_component` target is returned from `loadFrontendCatalog`. The `sourceRef` names the Studio hosted contribution of the package.
|
|
94
|
+
|
|
95
|
+
To add a component to the template:
|
|
96
|
+
|
|
97
|
+
1. Declare it in the `./ci` subpath of the package that owns it.
|
|
98
|
+
2. Add it to `packageComponents` after every component it references.
|
|
99
|
+
3. Bump `VERSION` in `packages/organization/acme/src/package.ts`. The package and every component share this one version.
|
|
100
|
+
|
|
101
|
+
## Lifecycle
|
|
102
|
+
|
|
103
|
+
Every content component sets `lifecycle: { deployMode, readonly }`.
|
|
104
|
+
|
|
105
|
+
| Option | Effect |
|
|
106
|
+
| ------------------------- | -------------------------------------------------------------------------------------------- |
|
|
107
|
+
| `deployMode: "upsert"` | Each deploy brings the definition back in line with the package. |
|
|
108
|
+
| `deployMode: "init_only"` | The first deploy creates the definition. Later deploys leave an administrator's edits alone. |
|
|
109
|
+
| `readonly: true` | Nobody can edit the definition by hand. Records of a schema stay editable. |
|
|
110
|
+
|
|
111
|
+
The template uses `upsert` with `readonly: true` for almost everything. The convert-lead workflow and the Sales reps grant use `init_only` with `readonly: false`, so an administrator can change them after install and an update keeps that change.
|
|
112
|
+
|
|
113
|
+
## Package variables
|
|
114
|
+
|
|
115
|
+
`packageVariables` declares values that change between environments and returns one typed handle per variable. You put the handle in a component definition where a value would go. The manifest stores `{ "$variable": "<name>" }` in its place, so the release digest is the same in every environment and CI substitutes the value at deploy.
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const variables = {
|
|
119
|
+
collection: {
|
|
120
|
+
type: "string",
|
|
121
|
+
default: "customers",
|
|
122
|
+
description: "Remote CRM collection"
|
|
123
|
+
},
|
|
124
|
+
companyDomains: { type: "string[]" },
|
|
125
|
+
crmToken: { type: "secret" }
|
|
126
|
+
} as const satisfies PackageVariablesDeclaration
|
|
127
|
+
|
|
128
|
+
const vars = packageVariables(variables)
|
|
129
|
+
// remoteCollectionId: vars.collection
|
|
130
|
+
|
|
131
|
+
export default declarePackage({ components, manifest, variables })
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
A variable has a type of `string`, `number`, `boolean`, `string[]`, `json` or `secret`. A variable without a default is required at deploy, and a `secret` cannot have a default. When a deploy provisions a secret without a value, the install still succeeds, but runtime use fails until an administrator sets it.
|
|
135
|
+
|
|
136
|
+
A handle cannot go in `fqn`, `version`, `kind`, `lifecycle`, a schema projection, or a reference to another component by FQN such as `schemaFqn` or `templateFqn`. The package FQN cannot be a variable either.
|
|
137
|
+
|
|
138
|
+
Connection slots work the same way at deploy. A component names a `{ setupKey }`, and the Inputs File gives either an existing `connectionId` or a `newConnection` with a name and fields. Installing a connector instance creates no records and starts no import. [Connectors](../data/connectors.md) covers instances and slots in detail.
|
|
139
|
+
|
|
140
|
+
## Deploy with ci deploy
|
|
141
|
+
|
|
142
|
+
`ci deploy` runs the whole release path for one declaration:
|
|
143
|
+
|
|
144
|
+
1. Build and validate the declaration.
|
|
145
|
+
2. Find the exact immutable release that matches the build.
|
|
146
|
+
3. Publish and promote the release only when CI does not have it yet.
|
|
147
|
+
4. Install it into the Organization, or update the existing installation.
|
|
148
|
+
5. Follow every operation until it succeeds.
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
ci deploy --backend-url https://ci.example.com --organization <organization-id> \
|
|
152
|
+
--declaration ./src/package.ts --non-interactive --json
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`ci deploy` reads two credentials. `CI_PUBLISHER_TOKEN` publishes and promotes, and `CI_MANAGEMENT_TOKEN` installs and updates in the Organization. If `CI_MANAGEMENT_TOKEN` is an Organization API key (prefix `dpk_`), you can omit `--organization`. `ci deploy --inputs-template` prints every connection slot and variable without contacting the backend.
|
|
156
|
+
|
|
157
|
+
A repeated deploy skips work that is already complete, and a new version updates the existing installation. CI rejects changed bytes under the same version and silent downgrades. Pass `--accept-breaking-changes` to acknowledge a breaking change. The default deadline is 300,000 ms, and `--timeout-ms` changes it.
|
|
158
|
+
|
|
159
|
+
> **Warning:** `--declaration` must start with `./` or be an absolute path, because the CLI
|
|
160
|
+
> resolves a bare `packages/...` like a module name and fails. A package with a
|
|
161
|
+
> Studio contribution waits until a Studio reports ready, and an unattended
|
|
162
|
+
> pipeline has no Studio, so pass `--skip-studio-readiness` there.
|
|
163
|
+
|
|
164
|
+
The long way runs each step by hand:
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
ci package build --declaration ./apps/extensions/src/index.ts --out apps/extensions/dist/release
|
|
168
|
+
ci package validate --archive .../release.tar --manifest .../manifest.json --package-manifest .../package-manifest.json
|
|
169
|
+
ci package publish --backend-url <url> --archive ... --manifest ... --package-manifest ... --idempotency-key <key>
|
|
170
|
+
ci package promote --backend-url <url> --release <release-id> --idempotency-key <key>
|
|
171
|
+
ci package install --backend-url <url> --organization <organization-id> --package acme.app.knowledge --release <release-id> --idempotency-key <key>
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`ci package build` writes `release.tar`, `manifest.json`, `package-manifest.json` and `private-source-maps/`. The source maps hold your full source, so keep them off any public origin. Publish, promote and install each return an Operation ID, and the step is done only when the operation reports `succeeded`. `ci package releases`, `update`, `rollback`, `sync` and `operation reconnect` cover the rest of the lifecycle.
|
|
175
|
+
|
|
176
|
+
Install records a Desired Release. CI makes it the Serving Release only after every required Host (Backend, Studio, Dashboard) has prepared it, so the backend and React parts of one package never run different versions. A failed generation never becomes Serving and leaves the previous Serving Release in place.
|
|
177
|
+
|
|
178
|
+
For a fast loop without releases, `ci package dev --backend-url <url> --declaration ./src/package.ts --host-origin <studio-or-dashboard-origin>` starts a Development Session. It serves modules with Vite and rebuilds on save until the command stops. It needs a `CI_MANAGEMENT_TOKEN` with `ai:manage`, and only one live command can own a package at a time.
|
|
179
|
+
|
|
180
|
+
## Runtime rules for backend code
|
|
181
|
+
|
|
182
|
+
Built-in packages ship with each CI version, use FQNs under `builtin.`, and run their backend code inside the CI backend process. Third-party backend code runs in Bun Workers. Each backend process keeps one Worker Pool per package release, and every Organization that uses that release shares it. Workers start on demand and stop after an idle period. Built-in and third-party packages use the same public SDK contracts.
|
|
183
|
+
|
|
184
|
+
> **Warning:** Never keep tenant data in module-level variables. Read the Organization,
|
|
185
|
+
> capabilities and configuration from the per-call `context`, because the next
|
|
186
|
+
> call in the same Worker can belong to a different Organization.
|
|
187
|
+
|
|
188
|
+
Every call gets an `AbortSignal` in `context.signal` and can have a deadline in `context.deadlineAt`. The host does not retry a failed call. A Worker that passes its heap limit is recycled without cutting the calls in flight. CI treats third-party code as trusted code: a valid publisher credential admits it to hosted execution, and Workers do not sandbox it.
|
|
189
|
+
|
|
190
|
+
## After install
|
|
191
|
+
|
|
192
|
+
Some parts of the demo need a person after the first deploy:
|
|
193
|
+
|
|
194
|
+
1. Rotate the client secret. A confidential application has no secret after install. An administrator with `external_apps:manage` runs `ci apps rotate-secret <application-id>` or clicks Rotate secret on the Dashboard External Apps page. CI shows the secret once, and the web app stores it as `CI_CLIENT_SECRET`.
|
|
195
|
+
2. Add users to the groups. The package creates groups empty and grants profiles to groups. In the template, an administrator adds users to the Sales group or its `managers` subgroup.
|
|
196
|
+
3. Set every secret variable that the deploy left without a value.
|
|
197
|
+
4. Enroll the web app with `ci apps enroll --env-file apps/web/.env.local`, which writes the `CI_*` values the server SDK reads.
|
|
198
|
+
|
|
199
|
+
The Dashboard Extensions page lists packages on Installed and Available tabs. Install and uninstall show a spinner until the real outcome, and leaving the page does not cancel the operation. A configured Knowledge connector instance, even a disabled one, or a saved connection blocks uninstall, and the Dashboard shows the error next to the package.
|
|
200
|
+
|
|
201
|
+
## Related pages
|
|
202
|
+
|
|
203
|
+
- [SDKs](sdks.md)
|
|
204
|
+
- [External apps](external-apps.md)
|
|
205
|
+
- [Access](../platform/access.md)
|
|
206
|
+
- [Template](../template/index.md)
|
|
207
|
+
- [Knowledge](../data/knowledge.md)
|
|
208
|
+
- [AI](../ai/index.md)
|
|
@@ -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)
|