@collective-intelligence/external-apps-server-sdk 0.1.41 → 0.2.1

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 ADDED
@@ -0,0 +1,41 @@
1
+ # `@collective-intelligence/external-apps-server-sdk`: agent guide
2
+
3
+ The confidential server SDK of Collective Intelligence (CI) external
4
+ applications: server clients, the BFF, Next.js route handlers, the Cache
5
+ Primitives, the Revalidate Route and the Effect services. The package
6
+ `README.md` holds the full API.
7
+
8
+ ## Rules
9
+
10
+ - Import each Effect API from `/effect`, the Next.js layer of `/effect` from
11
+ `/effect/next`, and `layerNodePostgres` from `/effect/node-postgres`. Import
12
+ route handlers, the BFF and the Cache Primitives from `/next`.
13
+ - Keep one `effect` (`^4.1.0`) in the app. It is a required peer.
14
+ - Write `"use cache"` in the app function that reads CI, and call
15
+ `cacheCiRead(client, ...)` in that scope. The SDK has no cached read, no
16
+ directive and no cache store.
17
+ - Give `cacheCiRead` only the service-mode server client (the app's own
18
+ credential). Keep user-scoped reads in TanStack Query on the client.
19
+ - Let SDK writes expire their tags: pass `invalidate: nextInvalidate`, or merge
20
+ `CacheInvalidation.layerNext` into the runtime. Keep `revalidateTag` for
21
+ writes that do not go through the SDK.
22
+ - Mount the Revalidate Route next to the ticket route, with the same
23
+ `secrets`.
24
+ - Branch on an error by its class (`instanceof`, `Effect.catchTag`) and its
25
+ `code`, not by its `message`.
26
+
27
+ ## Index
28
+
29
+ - [docs/next-cache.md](docs/next-cache.md): read when you cache a CI read in
30
+ Next.js, wire write invalidation, or run more than one instance.
31
+ - [docs/realtime.md](docs/realtime.md): read when you mount the ticket route
32
+ or the Revalidate Route, or a realtime change must refresh cached data.
33
+ - [docs/effect.md](docs/effect.md): read when you write server code with
34
+ Effect: services, layers, `Config`, the Read Port.
35
+ - [docs/errors.md](docs/errors.md): read when you handle a failed CI call.
36
+ - [skills/server-sdk-adopt-cache-primitives/SKILL.md](skills/server-sdk-adopt-cache-primitives/SKILL.md):
37
+ run when an app caches CI reads with its own tags or revalidates after SDK
38
+ writes by hand.
39
+ - [skills/server-sdk-move-to-effect/SKILL.md](skills/server-sdk-move-to-effect/SKILL.md):
40
+ run when code imports a deprecated subpath or an Effect API outside
41
+ `/effect`.
package/README.md CHANGED
@@ -1224,7 +1224,15 @@ import { ci } from "../server/ci" // createServerClient({ authentication: { mode
1224
1224
 
1225
1225
  export const getLead = async (organizationId: string, entityId: string) => {
1226
1226
  cacheCiRead(ci, { id: entityId, schema: "acme.crm.lead" })
1227
- return await ci.knowledge.getEntity({ entityId, organizationId })
1227
+ const answer = await ci.knowledge.query({
1228
+ organizationId,
1229
+ query: { entityId, op: "get" }
1230
+ })
1231
+ if (!answer.ok) {
1232
+ // Throw: the cache must not keep a CI error envelope.
1233
+ throw new Error(`CI read failed: ${answer.error.error.code}`)
1234
+ }
1235
+ return answer.value.result
1228
1236
  }
1229
1237
  ```
1230
1238
 
package/docs/effect.md ADDED
@@ -0,0 +1,76 @@
1
+ # Effect
2
+
3
+ `/effect` is the Effect API of the server SDK. The package root is a Vanilla
4
+ Facade over the same Effect Core: both load `effect`, and a class that both
5
+ export has one identity in the app.
6
+
7
+ ## Convention
8
+
9
+ - Import Effect APIs only from `/effect`. `/effect` loads no `next`, no `pg`
10
+ and no `drizzle-orm`.
11
+ - `/effect/next` holds `CacheInvalidation.layerNext` and loads `next`.
12
+ - `/effect/node-postgres` holds `layerNodePostgres` and loads `pg` and
13
+ `drizzle-orm`.
14
+ - `effect` `^4.1.0` is a required peer: keep one version in the app.
15
+ - The `ci-solution/effect-subpath` rule of `@collective-intelligence/lint`
16
+ reports an Effect API that comes from outside `/effect`, and the deprecated
17
+ subpaths. To move code, run
18
+ [the move skill](../skills/server-sdk-move-to-effect/SKILL.md).
19
+
20
+ ## Services and layers
21
+
22
+ Each client is one `Context.Service` with a `layer` and a `layerConfig` that
23
+ reads Effect `Config`.
24
+
25
+ | Service | Layers |
26
+ | -------------- | -------------------------------------------------------------------------------------------------------------------- |
27
+ | `ServerClient` | `layerServerClient`, `layerServerClientConfig`, `layerApplicationServerClient`, `layerApplicationServerClientConfig` |
28
+ | `CiEntities` | `layerCiEntities`, `layerCiEntitiesConfig` |
29
+
30
+ - `execute` fails with `CiError` or `CiTransportError`; `executeResult` keeps
31
+ the CI error envelope as a value. `records.create`, `update` and `delete`
32
+ fail with `CiError`; `recordsResult` keeps the refusal as a value.
33
+ - A `layer...Config` reads the client secret with `Config.Redacted`.
34
+ - Without a `sleep` option, the retry backoff is `Effect.sleep` on the
35
+ `Clock`, so `TestClock` drives it.
36
+ - `exchangeMemberSession(request)` fails with `MemberSessionExchangeError`.
37
+ - `CacheInvalidation` is a `Context.Reference` whose default does nothing.
38
+ The writes read it from their fiber: merge `CacheInvalidation.layerNext`
39
+ into the runtime next to the client layers, not with `Layer.provide` into
40
+ them. See [next-cache.md](next-cache.md#write-invalidation).
41
+
42
+ ```ts
43
+ import * as Effect from "effect/Effect"
44
+ import {
45
+ layerServerClient,
46
+ ServerClient
47
+ } from "@collective-intelligence/external-apps-server-sdk/effect"
48
+
49
+ const program = ServerClient.use((client) =>
50
+ client.execute("context_get", { organizationId })
51
+ ).pipe(
52
+ Effect.catchTag("CiError", (error) => Effect.succeed(error.code)),
53
+ Effect.provide(layerServerClient({ authentication, tenantUrl }))
54
+ )
55
+ ```
56
+
57
+ ## Read Port
58
+
59
+ Shared cached reads of an Effect server go through an app-owned `ReadPort`
60
+ service. The Next app supplies its `"use cache"` adapter; a passthrough layer
61
+ serves tests and runs outside Next. See
62
+ [next-cache.md](next-cache.md#effect-server-the-read-port).
63
+
64
+ ## Resources and gateways
65
+
66
+ - `makeEffectCrudResource` acquires the repository Effect once and returns the
67
+ portable `CrudResource` of the HTTP and gateway bindings.
68
+ - `createResourceEffectHandler` and `createGatewayEffectHandler` lift the
69
+ resource and the gateway kernel into Effect handlers. A request abort
70
+ interrupts the fiber.
71
+ - `jsonSchema`, `DateTimeString` and `UuidV7` give wire Schemas for resource
72
+ and operation definitions.
73
+
74
+ ## Errors
75
+
76
+ See [errors.md](errors.md).
package/docs/errors.md ADDED
@@ -0,0 +1,30 @@
1
+ # Errors
2
+
3
+ The server SDK uses the tagged error classes of
4
+ `@collective-intelligence/external-apps-client-sdk`. The package root and
5
+ `/effect` export the same classes, so `instanceof` gives one answer in the
6
+ app.
7
+
8
+ | Class | When |
9
+ | ---------------------------- | --------------------------------------------------------------------- |
10
+ | `CiError` | CI refused an operation: `code`, `message`, `retryable`, `details?` |
11
+ | `CiTransportError` | The request did not reach CI, or its answer was not readable: `cause` |
12
+ | `FederatedAuthError` | The federated sign-in failed: `code`, `message` |
13
+ | `MemberSessionExchangeError` | `exchangeMemberSession` failed |
14
+ | `GatewayEffectRuntimeError` | The Effect gateway runtime failed |
15
+
16
+ ## Rules
17
+
18
+ - A CI error envelope stays a value: `{ ok: false, error: { correlationId, error } }`.
19
+ Read `error.code`; keep `correlationId` in logs.
20
+ - A transport failure rejects (Promise) or fails (Effect) with
21
+ `CiTransportError`. Its `message` is empty: show the user your own text.
22
+ - An abort through `signal` rejects with `signal.reason`; in Effect it is an
23
+ interruption.
24
+ - Bad input, such as a bad `tenantUrl`, throws `TypeError`. Fix the call.
25
+ - `defineCiEntityResource` keeps each failure as a value of its
26
+ `ResourceResult`, with `transport_error` and its `outcome`.
27
+ - A failed cache invalidation after a confirmed write only logs a warning; the
28
+ write keeps its result.
29
+ - In Effect, branch with `Effect.catchTag("CiError", ...)`; decode a wire code
30
+ with the `CiErrorCode` Schema of `/effect`.
@@ -0,0 +1,120 @@
1
+ # Next.js cache
2
+
3
+ The Cache Primitives of `/next` give a CI read its cache tags and its
4
+ lifetime in Next.js Cache Components (Next.js 16, `cacheComponents: true`).
5
+ The app owns the `"use cache"` directive and the cache store. `/next` loads
6
+ `next`.
7
+
8
+ ## Cache a shared read
9
+
10
+ 1. Make a server client with the app's own credential:
11
+ `createServerClient({ authentication: { credentials, mode: "service" }, invalidate: nextInvalidate, tenantUrl })`.
12
+ 2. Write `"use cache"` at the start of the app function (or file) that reads.
13
+ 3. In that scope, call `cacheCiRead(client, { schema, id })` for a get, or
14
+ `cacheCiRead(client, { schema, filter })` for a filtered list, then read.
15
+
16
+ ```ts
17
+ import { cacheCiRead } from "@collective-intelligence/external-apps-server-sdk/next"
18
+
19
+ import { ci } from "./ci" // the service-mode server client
20
+
21
+ export const getLead = async (organizationId: string, entityId: string) => {
22
+ "use cache"
23
+ cacheCiRead(ci, { id: entityId, schema: "acme.crm.lead" })
24
+ const answer = await ci.knowledge.query({
25
+ organizationId,
26
+ query: { entityId, op: "get" }
27
+ })
28
+ if (!answer.ok) {
29
+ // Throw: the cache must not keep a CI error envelope.
30
+ throw new Error(`CI read failed: ${answer.error.error.code}`)
31
+ }
32
+ return answer.value.result
33
+ }
34
+ ```
35
+
36
+ - `schema` is the FQN of the schema.
37
+ - Read a get with `knowledge.query` and `op: "get"`. Return only the answer of
38
+ an ok result, and throw on an error envelope: a thrown read is not cached.
39
+ - Tags: `ciTag.all`, the Schema Tag, and the Entity Tag of a get or the Topic
40
+ Tag of a filtered list. To name a tag yourself, use `ciTag.entity(fqn, id)`,
41
+ `ciTag.schema(fqn)` or `ciTag.topic({ schema, filter })`. A tag is a
42
+ `CiTag`, a branded string; the SDK computes it.
43
+ - Lifetime: `life`, by default `{ stale: 60, revalidate: 60, expire: 86400 }`
44
+ seconds. A `life` replaces the default as a whole.
45
+ - `cacheCiRead` calls `cacheTag` and `cacheLife` of `next/cache`, so it works
46
+ only inside a `"use cache"` scope.
47
+
48
+ ## Credential rule
49
+
50
+ A cache entry goes to every visitor. So a cached read uses the app's own
51
+ credential:
52
+
53
+ - `cacheCiRead` type-checks only with `ServerClient<"service">`: a client whose
54
+ config has `authentication: { credentials, mode: "service" }`.
55
+ - A user-session client (`getAccessToken`, a token from
56
+ `exchangeMemberSession`), a client typed `ServerClient`, and the client of
57
+ `runAsApplication` do not type-check. This is the gate; keep it, with no
58
+ cast.
59
+ - User-scoped reads stay in TanStack Query on the client (the entity hooks of
60
+ `external-apps-client-sdk-react`). They never go into the shared cache.
61
+
62
+ ## Effect server: the Read Port
63
+
64
+ When the app API is an Effect server, keep `next` out of it:
65
+
66
+ - The server owns a `ReadPort` `Context.Service` with the shared reads.
67
+ - The Next app gives the adapter layer: each function has `"use cache"`,
68
+ calls `cacheCiRead`, and returns plain JSON from an uncached read.
69
+ - A passthrough layer reads CI through the `/effect` `ServerClient`, for tests
70
+ and for runs outside Next.
71
+ - Put into the port only reads that every signed-in user may see.
72
+
73
+ ## Write invalidation
74
+
75
+ After CI confirms a write, the SDK expires the Entity Tag and the Schema Tag
76
+ of its record, so the next read computes the entry again. This covers
77
+ `resources.records` writes and each write through the CI entity proxy
78
+ (`ciResources` of the BFF, `createCiResourceMounts`, `defineCiEntityResource`,
79
+ `CiEntities`). A read, and a write that CI refuses or that fails, expires
80
+ nothing.
81
+
82
+ | Code | Give it |
83
+ | ------------------------------------------------------------------ | ----------------------------------------------- |
84
+ | `createServerClient`, `runAsApplication` | `invalidate: nextInvalidate` |
85
+ | `ciResources`, `createCiResourceMounts`, `defineCiEntityResource` | `invalidate: nextInvalidate` |
86
+ | Effect runtime with `layerServerClient...` or `layerCiEntities...` | `CacheInvalidation.layerNext` of `/effect/next` |
87
+
88
+ - Merge `CacheInvalidation.layerNext` into the runtime, or provide it to the
89
+ program: `Layer.mergeAll(layerServerClientConfig(config), CacheInvalidation.layerNext)`.
90
+ The writes read it from their fiber, so `Layer.provide` of it to the client
91
+ layer does not reach them.
92
+ - `revalidateTag` runs only in a Route Handler or a Server Function. Write
93
+ there, not while a page renders.
94
+ - A failed invalidation does not fail the write: the write logs a warning and
95
+ keeps the record that CI confirmed. The old entry stays until its lifetime
96
+ ends.
97
+ - A write named by schema id reads the schema snapshot once per process to
98
+ find the FQN.
99
+
100
+ ## More than one instance
101
+
102
+ With the built-in in-memory store, each instance has its own cache. An
103
+ invalidation reaches only the instance that receives it; the other instances
104
+ serve old data until the lifetime ends. When that gap matters, configure a
105
+ shared store:
106
+
107
+ 1. Write a cache handler over shared storage. It implements `refreshTags`, so
108
+ each instance reads the tags that other instances expired.
109
+ 2. Register it under a kind name in `next.config.ts`:
110
+ `cacheHandlers: { neon: require.resolve("./cache-handlers/neon.mjs") }`.
111
+ 3. Use that kind in the shared reads: `"use cache: neon"`. `cacheCiRead`
112
+ works the same in that scope.
113
+
114
+ Example: apito plans a Neon cache handler, a handler whose storage is its Neon
115
+ database, used as `'use cache: neon'` for the shared CI reads only.
116
+
117
+ ## Realtime
118
+
119
+ The Revalidate Route expires the tags of the records that change in CI while
120
+ a tab is open. See [realtime.md](realtime.md).
@@ -0,0 +1,75 @@
1
+ # Realtime routes
2
+
3
+ A browser opens the CI realtime stream with a single-use ticket from the BFF,
4
+ never with the user's token. The server SDK gives two routes:
5
+
6
+ | Route | Handler of `/next` | Job |
7
+ | ------------------------------------- | --------------------------------- | -------------------------------------------------------------- |
8
+ | `POST {basePath}/realtime/ticket` | `createRealtimeTicketHandler` | Gets a CI ticket with the user's server-held token |
9
+ | `POST {basePath}/realtime/revalidate` | `createRealtimeRevalidateHandler` | Expires the Next.js cache tags of the changes that a tab posts |
10
+
11
+ `basePath` is `/api` by default. The browser client is in
12
+ `external-apps-client-sdk` (`createRealtimeClient`) and
13
+ `external-apps-client-sdk-react` (`RealtimeProvider`).
14
+
15
+ ## Mount both routes
16
+
17
+ ```ts
18
+ import {
19
+ createExternalApplicationBffNextHandlers,
20
+ createRealtimeRevalidateHandler
21
+ } from "@collective-intelligence/external-apps-server-sdk/next"
22
+
23
+ createExternalApplicationBffNextHandlers({
24
+ auth,
25
+ publicOrigin: env.APP_ORIGIN,
26
+ realtime: {
27
+ organizationId: env.CI_ORGANIZATION_ID,
28
+ revalidate: createRealtimeRevalidateHandler,
29
+ // The session secrets, the current one first.
30
+ secrets: [env.SESSION_SECRET],
31
+ tenantUrl: env.CI_TENANT_URL
32
+ }
33
+ })
34
+ ```
35
+
36
+ Then give the browser realtime client
37
+ `revalidateUrl: "/api/realtime/revalidate"`.
38
+
39
+ ## Topic Grant
40
+
41
+ - With `secrets`, each ticket answer also holds `grantToken`, the Topic Grant:
42
+ the topics that CI accepted, the session of the request, and an expiry 10
43
+ minutes after mint, sealed with the secret.
44
+ - The grant token is the only authority of the Revalidate Route. The route
45
+ refuses a token that is not its own, that expired, or that another session
46
+ got (403 `invalid_grant`), and a request without a session (401).
47
+ - It ignores a change whose topic is not in the token, and it never expires
48
+ `ci:all`.
49
+ - The token binds to the `sessionId` of the session that `auth.getSession`
50
+ gives. A custom `ApplicationUserAuth` without `sessionId` binds the token to
51
+ the user. Give a `sessionId` that stays the same for one session.
52
+ - The browser client renews the token 8 minutes after each ticket while the
53
+ stream stays open.
54
+
55
+ ## What the Revalidate Route expires
56
+
57
+ - For each accepted change: the Topic Tag (the Schema Tag for a topic without
58
+ a filter) and the Entity Tag. These are the tags that `cacheCiRead` writes;
59
+ see [next-cache.md](next-cache.md).
60
+ - `reset: true`, after a `reset` or `access-changed` event: the tag of each
61
+ topic in the token.
62
+ - It calls `revalidateTag(tag, { expire: 0 })`. On one instance, the first post
63
+ of a tag expires it at once and opens a 1-second window; more posts in the
64
+ window expire it once more at the window end, through `after`.
65
+ - A body holds at most 100 changes and 1 MiB (else 400 `invalid_request`). The
66
+ client splits a larger delivery.
67
+ - Each instance expires tags only for the posts that it receives. With the
68
+ built-in store, the other instances keep old entries; see
69
+ [next-cache.md](next-cache.md#more-than-one-instance).
70
+
71
+ ## Mount the routes yourself
72
+
73
+ Call `createRealtimeTicketHandler` and `createRealtimeRevalidateHandler` from
74
+ `/next` with the same `auth` and `secrets`. `secrets` needs
75
+ `auth.getSession`.
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "@collective-intelligence/external-apps-server-sdk",
3
- "version": "0.1.41",
3
+ "version": "0.2.1",
4
4
  "description": "Server-side client and proxy adapters for Collective Intelligence external applications.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "files": [
8
8
  "dist",
9
- "README.md"
9
+ "README.md",
10
+ "AGENTS.md",
11
+ "docs",
12
+ "skills"
10
13
  ],
11
14
  "main": "./dist/index.js",
12
15
  "types": "./dist/index.d.ts",
@@ -166,8 +169,8 @@
166
169
  "test:postgres": "bun tools/test-postgres.ts src/adapters/persistence/drizzle"
167
170
  },
168
171
  "dependencies": {
169
- "@collective-intelligence/extensions-sdk": "0.1.32",
170
- "@collective-intelligence/external-apps-client-sdk": "0.1.40",
172
+ "@collective-intelligence/extensions-sdk": "0.2.1",
173
+ "@collective-intelligence/external-apps-client-sdk": "0.2.1",
171
174
  "ajv": "8.20.0",
172
175
  "ajv-formats": "3.0.1",
173
176
  "jose": "6.2.9"
@@ -267,5 +270,5 @@
267
270
  "vitest": "5.0.2",
268
271
  "zod": "4.4.3"
269
272
  },
270
- "gitHead": "198553b0b3654e9c8b783533334d1a6a2156daae"
273
+ "gitHead": "7b3d604c39db3969749b14174d660a814a1f3a72"
271
274
  }
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: server-sdk-adopt-cache-primitives
3
+ description: Move the cached CI reads of a Next.js app to the Cache Primitives of `@collective-intelligence/external-apps-server-sdk/next`. Use when an app caches CI reads with its own tags or `unstable_cache`, calls `revalidateTag` after SDK writes, or turns on Cache Components.
4
+ ---
5
+
6
+ # Adopt the Cache Primitives
7
+
8
+ Reference: [next-cache.md](../../docs/next-cache.md),
9
+ [realtime.md](../../docs/realtime.md).
10
+
11
+ ## Steps
12
+
13
+ 1. **Inventory.** Search the app for `unstable_cache`, `cacheTag(`,
14
+ `cacheLife(`, `revalidateTag(`, `revalidatePath(` and `"use cache"` near
15
+ calls of the CI server client. Done when you have a list with each cached
16
+ CI read site and each manual revalidation after an SDK write.
17
+ 2. **Classify each read.** A read is _shared_ when it uses the app's own
18
+ credential and gives the same answer to every visitor; else it is
19
+ _user-scoped_. Done when each read of the list has one class.
20
+ 3. **Move the user-scoped reads out of the server cache.** Read them with
21
+ TanStack Query on the client (the entity hooks of
22
+ `external-apps-client-sdk-react`), or uncached on the server. Done when no
23
+ user-scoped read is in a `"use cache"` scope.
24
+ 4. **Tag the shared reads.** For each one: use the service-mode server client;
25
+ write `"use cache"` in the app function; call
26
+ `cacheCiRead(client, { schema, id })` or `{ schema, filter }` with the
27
+ schema FQN; remove the hand-written tags and `unstable_cache`. In an Effect
28
+ server, put the read behind the Read Port. Done when each shared read calls
29
+ `cacheCiRead` and type-checks with no cast on the client.
30
+ 5. **Wire write invalidation.** Pass `invalidate: nextInvalidate` to
31
+ `createServerClient`, `runAsApplication`, `ciResources`,
32
+ `createCiResourceMounts` and `defineCiEntityResource`; in an Effect runtime,
33
+ merge `CacheInvalidation.layerNext`. Remove each manual `revalidateTag` of
34
+ step 1 that follows an SDK write; keep the ones for other writes. Done when
35
+ each SDK write path has an invalidation and no manual call duplicates it.
36
+ 6. **Wire realtime, when the app has a realtime client.** Add `secrets` and
37
+ `revalidate: createRealtimeRevalidateHandler` to the BFF `realtime`
38
+ options, and `revalidateUrl` to the browser client. Done when the
39
+ Revalidate Route answers 204 to a post from a signed-in tab.
40
+ 7. **Check the instance count.** With more than one instance, configure a
41
+ shared cache handler and its `"use cache: <kind>"`. Done when the deploy has
42
+ one instance, or a shared handler with `refreshTags`.
43
+ 8. **Verify.** Run the app type-check and `next build`. Write a record through
44
+ the SDK, then read it through the cached function. Done when the build
45
+ passes and the read shows the new value.
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: server-sdk-move-to-effect
3
+ description: Move imports of `@collective-intelligence/external-apps-server-sdk` to the `/effect` convention. Use when code imports `/runtime/effect`, `/persistence/drizzle/effect` or `/runtime/next`, takes an Effect API from outside `/effect`, or lint reports `ci-solution/effect-subpath`.
4
+ ---
5
+
6
+ # Move to the `/effect` convention
7
+
8
+ Reference: [effect.md](../../docs/effect.md).
9
+
10
+ | Deprecated subpath | Import instead |
11
+ | ----------------------------- | ----------------------------------------------------------- |
12
+ | `/runtime/effect` | `/effect` |
13
+ | `/persistence/drizzle/effect` | `/effect`; `layerNodePostgres` from `/effect/node-postgres` |
14
+ | `/runtime/next` | `/next` |
15
+
16
+ The deprecated subpaths re-export the same values for one minor release, so
17
+ classes and service tags keep one identity while you move.
18
+
19
+ ## Steps
20
+
21
+ 1. **Find the imports.** Search for
22
+ `external-apps-server-sdk/runtime/effect`,
23
+ `external-apps-server-sdk/persistence/drizzle/effect` and
24
+ `external-apps-server-sdk/runtime/next`. Done when you have each import
25
+ site.
26
+ 2. **Rewrite each import** with the table. A type of a sibling SDK that the
27
+ old subpath re-exported comes from `@collective-intelligence/extensions-sdk`
28
+ or `@collective-intelligence/external-apps-client-sdk/resources`. Done when
29
+ step 1 finds nothing.
30
+ 3. **Keep `next` out of Effect code.** Code that runs outside Next imports
31
+ `/effect`, never `/next` or `/effect/next`; the Next app provides
32
+ `CacheInvalidation.layerNext`. Done when the Effect server package has no
33
+ `next` import.
34
+ 4. **Keep one `effect`.** The app has `effect` `^4.1.0` as a dependency, and
35
+ the lockfile holds one `effect@` version. Done when the lockfile check
36
+ shows one version.
37
+ 5. **Lint.** Extend the `recommended` config of `@collective-intelligence/lint`
38
+ in `oxlint.config.ts` and run oxlint. Done when it reports no
39
+ `ci-solution/effect-subpath` finding and the type-check passes.