@collective-intelligence/extensions-sdk-frontend 0.3.2 → 0.3.4
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/docs/guide/ai/index.md +36 -17
- package/docs/guide/ai/studio.md +245 -0
- package/docs/guide/data/connectors.md +81 -18
- package/docs/guide/data/datasets.md +6 -17
- package/docs/guide/data/documents.md +235 -0
- package/docs/guide/data/index.md +62 -0
- package/docs/guide/data/knowledge.md +21 -18
- package/docs/guide/develop/extensions.md +68 -15
- package/docs/guide/develop/external-apps.md +48 -14
- package/docs/guide/develop/infrastructure.md +135 -0
- package/docs/guide/develop/sdks.md +2 -2
- package/docs/guide/index.md +12 -8
- package/docs/guide/platform/access.md +82 -17
- package/docs/guide/platform/architecture.md +27 -18
- package/docs/guide/platform/entrypoints.md +128 -47
- package/docs/guide/scenarios/index.md +69 -46
- package/docs/guide/template/index.md +22 -9
- package/docs/guide/template/state-machines.md +1 -1
- package/package.json +3 -3
|
@@ -8,58 +8,80 @@ Some screens need no primitive at all. The template's public intake form posts t
|
|
|
8
8
|
|
|
9
9
|
## Decision path
|
|
10
10
|
|
|
11
|
+
A scenario raises three separate questions: where its data lives, what kind of work it needs, and who uses its screens. Answer each one with its own chart and combine the results.
|
|
12
|
+
|
|
13
|
+
### Where the data lives
|
|
14
|
+
|
|
15
|
+
The first question is who keeps the authoritative copy of the data. [Data resources](../data/index.md) compares Knowledge, datasets and Documents in more depth.
|
|
16
|
+
|
|
17
|
+
```mermaid
|
|
18
|
+
flowchart TD
|
|
19
|
+
D{Who keeps the authoritative copy?}
|
|
20
|
+
D -->|CI| M{What shape is the data?}
|
|
21
|
+
M -->|Records that people and agents edit| K[Knowledge schema]
|
|
22
|
+
M -->|Rows to read and aggregate| MD[Managed dataset]
|
|
23
|
+
M -->|Files that people browse and agents search| DOC[Documents]
|
|
24
|
+
D -->|An outside system| X{How does CI reach it?}
|
|
25
|
+
X -->|Live queries on a warehouse| XD[External dataset]
|
|
26
|
+
X -->|Records and actions in the customer app| GW[Gateway]
|
|
27
|
+
X -->|A copy in CI kept in sync| CON[Knowledge connector]
|
|
28
|
+
D -->|Only the app| APP[App-owned storage]
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
A Knowledge connector turns the outside records into connected records in Knowledge. When agents need only a few fields of an app database, put a projection of those fields into a Knowledge schema and keep personal data in the app.
|
|
32
|
+
|
|
33
|
+
### What kind of work it needs
|
|
34
|
+
|
|
35
|
+
```mermaid
|
|
36
|
+
flowchart TD
|
|
37
|
+
W{What kind of work is it?}
|
|
38
|
+
W -->|A rule with one right answer| T[Tool]
|
|
39
|
+
W -->|Fixed steps in a fixed order| WF[Workflow]
|
|
40
|
+
W -->|A path that depends on what it finds| AG[Agent with a Skill]
|
|
41
|
+
W -->|Logic that an existing backend already runs| RT[Gateway with a remote tool collection]
|
|
42
|
+
WF --> A{Must a person approve a side effect?}
|
|
43
|
+
AG --> A
|
|
44
|
+
A -->|Inside the workflow| AN[Workflow approval node]
|
|
45
|
+
A -->|In chat or a Skill form| TA[Tool binding with approval]
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A file that feeds one extraction step goes to a workflow as its input. [Workflow, agent or tool](index.md#workflow-agent-or-tool) and [Approvals depend on the caller](index.md#approvals-depend-on-the-caller) below explain the hard cases.
|
|
49
|
+
|
|
50
|
+
### Who uses the screens
|
|
51
|
+
|
|
11
52
|
```mermaid
|
|
12
53
|
flowchart TD
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
Q3 -->|Agents need a few fields| K
|
|
20
|
-
Q1 -->|Only the app needs it| APP[App-owned storage]
|
|
21
|
-
S --> Q4{Is it files?}
|
|
22
|
-
Q4 -->|People browse, agents search| DOC[Documents]
|
|
23
|
-
Q4 -->|One extraction step| WF[Workflow]
|
|
24
|
-
S --> Q5{Does it come from a SaaS?}
|
|
25
|
-
Q5 -->|Recurring import| CON[Connector]
|
|
26
|
-
S --> Q6{Deterministic or open-ended?}
|
|
27
|
-
Q6 -->|Fixed steps| WF
|
|
28
|
-
Q6 -->|Open-ended| AG["Agent + Skill"]
|
|
29
|
-
Q6 -->|One fixed rule| T[Tool]
|
|
30
|
-
S --> Q7{Does a side effect need approval?}
|
|
31
|
-
Q7 -->|In chat or a Skill form| TA[Tool with approval]
|
|
32
|
-
Q7 -->|Inside a process| AN[Workflow approval node]
|
|
33
|
-
S --> Q8{Who uses the UI?}
|
|
34
|
-
Q8 -->|Customers outside CI| EA[External app]
|
|
35
|
-
Q8 -->|Staff inside Studio| SA[Studio app]
|
|
36
|
-
S --> Q9{Must agents call existing backend logic?}
|
|
37
|
-
Q9 -->|Yes| GW["Gateway + remote tool collection"]
|
|
54
|
+
U{Who uses the screen?}
|
|
55
|
+
U -->|Customers or members outside CI| EA[External app with a BFF]
|
|
56
|
+
U -->|Staff in Studio| S{Do the built-in views show it?}
|
|
57
|
+
S -->|Yes| BV[Studio app with built-in views]
|
|
58
|
+
S -->|No| CW[Studio app with a custom widget]
|
|
59
|
+
U -->|Nobody yet, a first visual pitch| MOCK[Mock screens with simulated saves]
|
|
38
60
|
```
|
|
39
61
|
|
|
40
|
-
The
|
|
62
|
+
The sales CRM answers the data chart with Knowledge schemas and the work chart with a workflow, an agent and a tool. It answers the screen chart twice: customers use the external app, and staff use a Studio app that places a built-in list view and a custom widget on one page.
|
|
41
63
|
|
|
42
64
|
## Criteria
|
|
43
65
|
|
|
44
|
-
| Signal in the scenario | Primitive
|
|
45
|
-
| ----------------------------------------------------------------------------------------- |
|
|
46
|
-
| People in the app or Studio, agents and workflows all read and edit the records | [Knowledge schema](../data/knowledge.md)
|
|
47
|
-
| Rows that people read and aggregate, such as a CSV or Excel export with trends | [Managed dataset](../data/datasets.md)
|
|
48
|
-
| A warehouse such as Microsoft Fabric or Databricks holds the data, and it must stay there | [External dataset](../data/datasets.md)
|
|
49
|
-
| The customer's own app and database keep the records | [Gateway](../develop/external-apps.md)
|
|
50
|
-
| The app database is the authority, but agents need some of its fields | [Knowledge schema](../data/knowledge.md) with a projection
|
|
51
|
-
| Files that people browse and agents search | [Documents](../data/
|
|
52
|
-
| A file that feeds one extraction step and nothing else | Stored file passed to a [workflow](../ai/index.md)
|
|
53
|
-
| A SaaS tool or SQL database that the demo imports from on a schedule | [Knowledge connector](../data/connectors.md)
|
|
54
|
-
| A fixed sequence such as extract, check, create and notify | [Workflow](../ai/index.md)
|
|
55
|
-
| Open-ended work such as answering questions, finding matches or qualifying | [Agent with a Skill](../ai/index.md)
|
|
56
|
-
| A rule that must give the same answer every time | [Tool](../ai/index.md)
|
|
57
|
-
| A side effect that a person must approve | [Tool binding with approval](../ai/index.md), or a workflow approval node
|
|
58
|
-
| Customers or members use the UI outside CI | [External application](../develop/external-apps.md)
|
|
59
|
-
| Staff work inside Studio | [Studio app](../develop/extensions.md)
|
|
60
|
-
| Agents must call logic that an existing backend already implements | [Gateway with a remote tool collection](../develop/external-apps.md)
|
|
61
|
-
| Some people may see or do things that others may not | [Access Profiles and Access Grants](../platform/access.md)
|
|
62
|
-
| Logs, counters or sessions that only the app needs | App-owned storage behind the app API
|
|
66
|
+
| Signal in the scenario | Primitive | Why | Watch out for |
|
|
67
|
+
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
68
|
+
| People in the app or Studio, agents and workflows all read and edit the records | [Knowledge schema](../data/knowledge.md) | One typed record per real thing, with relations, search and data policies that every surface shares | Measurements, events and other high-volume rows belong in a dataset, so do not create one record per row |
|
|
69
|
+
| Rows that people read and aggregate, such as a CSV or Excel export with trends | [Managed dataset](../data/datasets.md) | CI stores the typed rows and answers records, aggregate and time-series queries | A dataset declared with no data policy grants access to nobody, and deploy does not import the file |
|
|
70
|
+
| A warehouse such as Microsoft Fabric or Databricks holds the data, and it must stay there | [External dataset](../data/datasets.md) | CI queries the source live and keeps no copy | Queries take no SQL, and a provider outage fails the query with no fallback |
|
|
71
|
+
| The customer's own app and database keep the records | [Gateway](../develop/external-apps.md) | CI reaches the resources, dataset queries and operations that the customer server declares | The Gateway exposes only what its definition lists and never creates CI schemas |
|
|
72
|
+
| The app database is the authority, but agents need some of its fields | [Knowledge schema](../data/knowledge.md) with a projection | Only the needed, non-personal fields leave the app | Decide field by field what may leave; personal data stays in the app database |
|
|
73
|
+
| Files that people browse and agents search | [Documents](../data/documents.md) in a Document Collection | Collections hold folders, versions and permissions per path, and a connected collection stays in sync with a drive | A [Documents connector](../data/connectors.md) sync creates no Knowledge records, and new files become searchable only after indexing |
|
|
74
|
+
| A file that feeds one extraction step and nothing else | Stored file passed to a [workflow](../ai/index.md) | The workflow takes the file as `storageFileId` and returns extracted values | Use Documents instead when people must find the file later |
|
|
75
|
+
| A SaaS tool or SQL database that the demo imports from on a schedule | [Knowledge connector](../data/connectors.md) | A connector instance maps source fields to Knowledge schemas and runs full or delta imports | Installing the instance imports nothing until a schedule or a manual trigger runs, and SQL delta imports need a watermark column |
|
|
76
|
+
| A fixed sequence such as extract, check, create and notify | [Workflow](../ai/index.md) | A graph of steps with triggers, approvals and typed output, where a prompt node covers one bounded AI step | Every triggered workflow needs a service principal as its run-as identity |
|
|
77
|
+
| Open-ended work such as answering questions, finding matches or qualifying | [Agent with a Skill](../ai/index.md) | The agent picks its path from what it finds and returns typed output inside stated boundaries | A Skill can use only tools that its agent also allows, so the agent lists the Skill's tools again |
|
|
78
|
+
| A rule that must give the same answer every time | [Tool](../ai/index.md) | Code computes the result, and the agent explains it | An agent can call the tool only when its `usageScopes` include `"automation"` |
|
|
79
|
+
| A side effect that a person must approve | [Tool binding with approval](../ai/index.md), or a workflow approval node | `approval: "always"` or a named rule pauses the call until someone decides | A named rule must exist in the Organization before install, and an unattended agent run approves by default |
|
|
80
|
+
| Customers or members use the UI outside CI | [External application](../develop/external-apps.md) | The web app keeps its own UI and reaches CI through its BFF with a sealed-cookie session | The app takes no OAuth scopes; its app gate and Max Privileges limit what users can do |
|
|
81
|
+
| Staff work inside Studio | [Studio app](../develop/extensions.md) | Built-in views show schema records without code, and custom widgets cover what they cannot show | A Declared Studio App is read-only in the Studio builder and changes only with a new package release |
|
|
82
|
+
| Agents must call logic that an existing backend already implements | [Gateway with a remote tool collection](../develop/external-apps.md) | The logic stays in the customer service and reaches agents as tools | CI signs a short-lived token for every Gateway call, and browser cookies never authorize one |
|
|
83
|
+
| Some people may see or do things that others may not | [Access Profiles and Access Grants](../platform/access.md) | Capabilities and Knowledge data policies decide actions and visible records, and grants give them to Groups | Knowledge data policies do not cover datasets, which list their principals in their own policy |
|
|
84
|
+
| Logs, counters or sessions that only the app needs | App-owned storage behind the app API | No CI user or agent reads this data | A staff page that shows it needs its own credential in the app |
|
|
63
85
|
|
|
64
86
|
## Workflow, agent or tool
|
|
65
87
|
|
|
@@ -67,7 +89,7 @@ A workflow prompt node and an agent both call a model, which makes this the choi
|
|
|
67
89
|
|
|
68
90
|
An agent that must not change data says so in `behavioralBoundaries`. The lead qualifier declares "Never change a Lead or create an Opportunity". When an agent should help with a change, let it propose the change and let the person apply it with a button in the app.
|
|
69
91
|
|
|
70
|
-
A workflow's trigger follows from who or what starts the work. A `schedule` trigger runs it on a clock, `entity-created` and `entity-updated` react to Knowledge changes, `external-application` lets the web app start it, and `on-demand` lets staff start it from Studio. The template's convert-lead workflow uses the `external-application` trigger
|
|
92
|
+
A workflow's trigger follows from who or what starts the work. A `schedule` trigger runs it on a clock, `entity-created` and `entity-updated` react to Knowledge changes, `external-application` lets the web app start it, and `on-demand` lets staff start it from Studio. A run acts as the identity that started it: by default a person who starts it runs it as themselves, a workflow in `service_principal` run identity mode runs as its run-as service principal, and a start with no person, such as a schedule or a record event, needs that mode. The template's convert-lead workflow uses the `external-application` trigger, runs as the signed-in user when the web app starts it with the user's token, and names `convert-lead-runner` as its run-as service principal. See [AI](../ai/index.md) for the full comparison of tools, Skills, agents and workflows.
|
|
71
93
|
|
|
72
94
|
## Approvals depend on the caller
|
|
73
95
|
|
|
@@ -99,6 +121,7 @@ Demos built from the template started with Knowledge schemas, access and an exte
|
|
|
99
121
|
|
|
100
122
|
- [Knowledge](../data/knowledge.md)
|
|
101
123
|
- [Datasets](../data/datasets.md)
|
|
124
|
+
- [Documents](../data/documents.md)
|
|
102
125
|
- [Connectors](../data/connectors.md)
|
|
103
126
|
- [AI](../ai/index.md)
|
|
104
127
|
- [External apps](../develop/external-apps.md)
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
-
`next-effect-app` is the starting point for every demo. It is a bun and Turborepo monorepo with one Next.js 16 App Router web app (`apps/web`) and one Extension Package declaration (`apps/extensions`). You start a demo by generating a new repository from
|
|
5
|
+
`next-effect-app` is the starting point for every demo. It is a bun and Turborepo monorepo with one Next.js 16 App Router web app (`apps/web`) and one Extension Package declaration (`apps/extensions`). You start a demo by generating a new repository from the [template repository](https://github.com/collective-intelligence-solutions/next-effect-app) with **Use this template** on GitHub. The template repository is private, so your GitHub account needs access to it. Its example features are patterns to copy: a demo keeps their shape and replaces their content with the customer's domain.
|
|
6
6
|
|
|
7
7
|
## What you get
|
|
8
8
|
|
|
@@ -163,7 +163,7 @@ The BFF holds the CI session in a sealed cookie and proxies resource calls, so t
|
|
|
163
163
|
|
|
164
164
|
## Start a new demo
|
|
165
165
|
|
|
166
|
-
1. Generate a repository with **Use this template
|
|
166
|
+
1. Generate a repository with **Use this template** on the template repository. In the new repository, delete the README "Contributing" section and `.github/workflows/close-pull-requests.yml`, which only matter in the template repository itself.
|
|
167
167
|
2. Rename the template for the customer. Replace the `@acme/` package scopes and the `acme.app.` FQNs, replace `https://acme.localhost` in `packages/organization/acme/src/application.ts` and `.env.example`, and replace the theme tokens and the sidebar brand in `apps/web/src/composition/routing/shells/workspace/app-sidebar.tsx`. Theme tokens live once, in `packages/modules/ui/src/styles/globals.css`.
|
|
168
168
|
3. Run it locally. The Overview and Lead intake pages work with no configuration, because the intake API keeps requests in memory:
|
|
169
169
|
|
|
@@ -193,24 +193,37 @@ The BFF holds the CI session in a sealed cookie and proxies resource calls, so t
|
|
|
193
193
|
|
|
194
194
|
Running `package build` into a scratch folder and then `package validate` is the dry run for any change to the package.
|
|
195
195
|
|
|
196
|
-
5.
|
|
196
|
+
5. Connect the web app to its CI application. Installing the package registered `acme.app.application` as a confidential client with no secret. Sign in to the CLI as an Organization admin, copy the env example, write the connection values and issue the sign-in secret:
|
|
197
197
|
|
|
198
198
|
```bash
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
199
|
+
ci login <api-url> --organization <organization-id>
|
|
200
|
+
cp apps/web/.env.example apps/web/.env.local
|
|
201
|
+
ci apps env acme.app.application --env-file apps/web/.env.local
|
|
202
|
+
ci apps rotate-secret <application-id>
|
|
203
203
|
```
|
|
204
204
|
|
|
205
|
-
|
|
205
|
+
`ci apps env` writes `CI_ISSUER`, `CI_AUDIENCE`, `CI_APPLICATION_ID`, `CI_CLIENT_ID`, `CI_ORGANIZATION_ID` and `CI_JWKS_URL` into the file and changes nothing in CI. It leaves out the client secret and prints the `ci apps rotate-secret` command with the Application Id. `ci apps rotate-secret` prints the new sign-in secret once, as `clientSecret`; store it as `CI_CLIENT_SECRET` in `apps/web/.env.local`. Then set `APP_ORIGIN`, `CI_TENANT_URL`, `SESSION_SECRETS` and `NEXT_PUBLIC_APPLICATION_ID`, which equals `CI_APPLICATION_ID` and is the only value the browser sees.
|
|
206
206
|
|
|
207
|
-
|
|
207
|
+
The sign-in secret only signs users in. The server's own reads, such as the Read Port, need a Server Credential in a separate env file:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
ci apps credentials upsert acme.app.application --name web --env-file apps/web/.env.server
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
CI shows its secret once and writes it only to that file. The Server Credential acts with the grants given to the app's server, and the package declares none, so an Organization admin also gives the app server read access to Leads. Management tokens never go to Next.
|
|
214
|
+
|
|
215
|
+
6. Add users to the Sales group. CI accepts a user's token only when the user holds the application gate, so nobody can sign in yet. An Organization admin adds each user to the Sales group (Sales rep profile) or to its `managers` subgroup (Sales manager profile).
|
|
208
216
|
7. Sign in over HTTPS. The sealed session cookie requires HTTPS, so serve the dev server through a local HTTPS proxy:
|
|
209
217
|
|
|
210
218
|
```bash
|
|
211
219
|
portless acme bun run dev:web # https://acme.localhost
|
|
212
220
|
```
|
|
213
221
|
|
|
222
|
+
> **Warning:** Use `ci apps env` for the template's application. `ci apps enroll` refuses an
|
|
223
|
+
> application that a package declared. Run `ci apps env` before you paste the
|
|
224
|
+
> secret, because it refuses to write a file whose secret belongs to another
|
|
225
|
+
> Client Id.
|
|
226
|
+
|
|
214
227
|
> **Warning:** The `./` in `--declaration ./apps/extensions/src/index.ts` is required.
|
|
215
228
|
> Without it, the CLI resolves the path like a module name and fails.
|
|
216
229
|
|
|
@@ -279,7 +279,7 @@ Most demo flows need no Model. Add a `*.proof.ts` only when the flow has one of
|
|
|
279
279
|
- recovery or resync
|
|
280
280
|
- a delivery guarantee such as "eventually delivered"
|
|
281
281
|
|
|
282
|
-
In the template, only the optimistic write against a Realtime refetch met that bar. Write one Model per service: the state the service owns becomes a top-level `let`, and each dependency stays outside and enters only as an action. The SDKs ship their own Models for the optimistic write coordinator, the session, the Realtime machine, change-log resync and topic grant tokens, so
|
|
282
|
+
In the template, only the optimistic write against a Realtime refetch met that bar. Write one Model per service: the state the service owns becomes a top-level `let`, and each dependency stays outside and enters only as an action. The SDKs ship their own Models for the optimistic write coordinator, the session, the Realtime machine, change-log resync and topic grant tokens, so an app inherits those guarantees and models only its own flows.
|
|
283
283
|
|
|
284
284
|
### Sensitivity Proofs
|
|
285
285
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@collective-intelligence/extensions-sdk-frontend",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.4",
|
|
4
4
|
"description": "Framework-neutral frontend declaration, catalog, and activation contracts for Collective Intelligence extension packages.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"access": "public"
|
|
45
45
|
},
|
|
46
46
|
"dependencies": {
|
|
47
|
-
"@collective-intelligence/extensions-sdk": "0.3.
|
|
47
|
+
"@collective-intelligence/extensions-sdk": "0.3.4"
|
|
48
48
|
},
|
|
49
49
|
"peerDependencies": {
|
|
50
50
|
"effect": "^4.1.0"
|
|
@@ -63,5 +63,5 @@
|
|
|
63
63
|
"typescript": "7.0.2",
|
|
64
64
|
"ultracite": "7.10.7"
|
|
65
65
|
},
|
|
66
|
-
"gitHead": "
|
|
66
|
+
"gitHead": "dc0b867b4eb6fef705bc55ed670db4ac7deeaf4a"
|
|
67
67
|
}
|