@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 +41 -0
- package/README.md +9 -1
- package/docs/effect.md +76 -0
- package/docs/errors.md +30 -0
- package/docs/next-cache.md +120 -0
- package/docs/realtime.md +75 -0
- package/package.json +8 -5
- package/skills/server-sdk-adopt-cache-primitives/SKILL.md +45 -0
- package/skills/server-sdk-move-to-effect/SKILL.md +39 -0
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
|
-
|
|
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).
|
package/docs/realtime.md
ADDED
|
@@ -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
|
|
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
|
|
170
|
-
"@collective-intelligence/external-apps-client-sdk": "0.1
|
|
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": "
|
|
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.
|