@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 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
- Three subpaths are deprecated re-exports for one minor release. Each exports
46
- the same values as its replacements, so classes and service tags have one
47
- identity. Each name that a subpath takes from its replacement is marked
48
- `@deprecated`, and the `ci-solution/effect-subpath` lint rule reports the
49
- subpaths. The replacements do not export the types of the sibling SDKs that
50
- the deprecated subpaths kept from 0.1.x: import them from
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
- | Deprecated subpath | Import instead |
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
- return await ci.knowledge.getEntity({ entityId, organizationId })
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`, `/effect/node-postgres` and `/persistence/drizzle/effect`. The
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 DrizzlePostgres3 extends Context.Service()("@collective-intelligence/external-apps-server-sdk/DrizzlePostgres"){}var layerFromDatabase3=(value)=>Layer.succeed(DrizzlePostgres3,value);import*as Schema from"effect/Schema";class DrizzlePostgresInitializationError3 extends Schema.TaggedError()("DrizzlePostgresInitializationError",{cause:Schema.Defect()}){}
2
- export{makeDatabase,DrizzlePostgres3,layerFromDatabase3,DrizzlePostgresInitializationError3};
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};