@collective-intelligence/external-apps-server-sdk 0.2.0 → 0.2.2
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 +17 -13
- package/dist/chunks/{index-8yk07eg5.js → index-4z962jdh.js} +2 -2
- package/dist/chunks/{index-mp74xvyn.js → index-qe1587f9.js} +3 -3
- package/dist/effect/node-postgres.js +1 -1
- package/dist/effect.d.ts +1 -1
- package/dist/effect.js +1 -1
- package/dist/index.js +1 -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 -23
- package/skills/server-sdk-adopt-cache-primitives/SKILL.md +45 -0
- package/skills/server-sdk-move-to-effect/SKILL.md +41 -0
- package/dist/chunks/index-ees2k4z3.js +0 -2
- package/dist/chunks/index-pzge02c9.js +0 -2
- package/dist/persistence/drizzle-effect.d.ts +0 -58
- package/dist/persistence/drizzle-effect.js +0 -1
- package/dist/runtime/effect.d.ts +0 -477
- package/dist/runtime/next.d.ts +0 -526
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 removed subpath or an Effect API outside
|
|
41
|
+
`/effect`.
|
package/README.md
CHANGED
|
@@ -42,24 +42,20 @@ layer of `/effect` ([Write invalidation](#write-invalidation)) and loads
|
|
|
42
42
|
|
|
43
43
|
### Subpath migration
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
`@collective-intelligence/extensions-sdk` or
|
|
45
|
+
**Breaking:** the release after 0.2.0 removes three subpaths. In 0.2.0 each
|
|
46
|
+
was a deprecated re-export of its replacement. An import of a removed subpath
|
|
47
|
+
fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`, and the
|
|
48
|
+
`ci-solution/effect-subpath` lint rule reports it. The replacements do not
|
|
49
|
+
export the types of the sibling SDKs that the removed subpaths kept from
|
|
50
|
+
0.1.x: import them from `@collective-intelligence/extensions-sdk` or
|
|
52
51
|
`@collective-intelligence/external-apps-client-sdk/resources`.
|
|
53
52
|
|
|
54
|
-
|
|
|
53
|
+
| Removed subpath | Import instead |
|
|
55
54
|
| ----------------------------- | ----------------------------------------------------------- |
|
|
56
55
|
| `/runtime/effect` | `/effect` |
|
|
57
56
|
| `/persistence/drizzle/effect` | `/effect`; `layerNodePostgres` from `/effect/node-postgres` |
|
|
58
57
|
| `/runtime/next` | `/next` |
|
|
59
58
|
|
|
60
|
-
`/persistence/drizzle/effect` imports `pg` and `drizzle-orm`, as
|
|
61
|
-
`/effect/node-postgres` does.
|
|
62
|
-
|
|
63
59
|
### Errors
|
|
64
60
|
|
|
65
61
|
The SDK uses the tagged error classes of
|
|
@@ -1224,7 +1220,15 @@ import { ci } from "../server/ci" // createServerClient({ authentication: { mode
|
|
|
1224
1220
|
|
|
1225
1221
|
export const getLead = async (organizationId: string, entityId: string) => {
|
|
1226
1222
|
cacheCiRead(ci, { id: entityId, schema: "acme.crm.lead" })
|
|
1227
|
-
|
|
1223
|
+
const answer = await ci.knowledge.query({
|
|
1224
|
+
organizationId,
|
|
1225
|
+
query: { entityId, op: "get" }
|
|
1226
|
+
})
|
|
1227
|
+
if (!answer.ok) {
|
|
1228
|
+
// Throw: the cache must not keep a CI error envelope.
|
|
1229
|
+
throw new Error(`CI read failed: ${answer.error.error.code}`)
|
|
1230
|
+
}
|
|
1231
|
+
return answer.value.result
|
|
1228
1232
|
}
|
|
1229
1233
|
```
|
|
1230
1234
|
|
|
@@ -1425,7 +1429,7 @@ Next.js app with `output: "standalone"` gets them in its output without a
|
|
|
1425
1429
|
bundler with `Module not found`. A bad pool config or a failed migration fails
|
|
1426
1430
|
the layer with `DrizzlePostgresInitializationError`.
|
|
1427
1431
|
`DrizzlePostgres` and `DrizzlePostgresInitializationError` have one identity
|
|
1428
|
-
in `/effect
|
|
1432
|
+
in `/effect` and `/effect/node-postgres`. The
|
|
1429
1433
|
declarations of `/effect` and `/effect/node-postgres` refer to `drizzle-orm`
|
|
1430
1434
|
and `pg` types: an application that type checks with `skipLibCheck: false`
|
|
1431
1435
|
installs `drizzle-orm` and `@types/pg`.
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import*as Context from"effect/Context";import*as Layer from"effect/Layer";var makeDatabase=(drizzle,pool)=>drizzle({client:pool});class
|
|
2
|
-
export{makeDatabase,
|
|
1
|
+
import*as Context from"effect/Context";import*as Layer from"effect/Layer";var makeDatabase=(drizzle,pool)=>drizzle({client:pool});class DrizzlePostgres2 extends Context.Service()("@collective-intelligence/external-apps-server-sdk/DrizzlePostgres"){}var layerFromDatabase2=(value)=>Layer.succeed(DrizzlePostgres2,value);import*as Schema from"effect/Schema";class DrizzlePostgresInitializationError2 extends Schema.TaggedError()("DrizzlePostgresInitializationError",{cause:Schema.Defect()}){}
|
|
2
|
+
export{makeDatabase,DrizzlePostgres2,layerFromDatabase2,DrizzlePostgresInitializationError2};
|