@collective-intelligence/extensions-sdk-frontend 0.3.2 → 0.3.3

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.
@@ -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 it with **Use this template** on GitHub. Its example features are patterns to copy: a demo keeps their shape and replaces their content with the customer's domain.
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**. In the new repository, delete the README "Contributing" section and `.github/workflows/close-pull-requests.yml`, which only matter in the template repository itself.
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. Rotate the application secret. The package installs a confidential application without a secret, so an Organization administrator rotates one:
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
- curl -sS -X POST \
200
- -H "authorization: Bearer <administrator-token>" \
201
- -H "x-organization-id: <organization-id>" \
202
- <url>/admin/organization/external-apps/<application-id>/credential/rotate
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
- Copy `apps/web/.env.example` to `apps/web/.env.local`. Store `clientSecret` as `CI_CLIENT_SECRET`, `application.clientId` as `CI_CLIENT_ID` and the application id as `CI_APPLICATION_ID`. Then set `APP_ORIGIN`, `CI_TENANT_URL`, `CI_ISSUER`, `CI_AUDIENCE`, `CI_ORGANIZATION_ID`, `SESSION_SECRETS` and `NEXT_PUBLIC_APPLICATION_ID`, which equals `CI_APPLICATION_ID` and is the only value the browser sees. `ci apps enroll --env-file apps/web/.env.local` writes the enrollment values for you. Management tokens never go to Next.
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
- 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 administrator adds each user to the Sales group (Sales rep profile) or to its `managers` subgroup (Sales manager profile).
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 a demo inherits those guarantees and models only its own flows.
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.2",
3
+ "version": "0.3.3",
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.2"
47
+ "@collective-intelligence/extensions-sdk": "0.3.3"
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": "468c45b8c46fc4e893cd9c7f5e77e7fa0ffd557b"
66
+ "gitHead": "cd2b929b7ef35008f1acb284a4b8966f5c9cfaca"
67
67
  }