@collective-intelligence/external-apps-server-sdk 0.2.1 → 0.2.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.
package/AGENTS.md CHANGED
@@ -19,6 +19,12 @@ Primitives, the Revalidate Route and the Effect services. The package
19
19
  - Let SDK writes expire their tags: pass `invalidate: nextInvalidate`, or merge
20
20
  `CacheInvalidation.layerNext` into the runtime. Keep `revalidateTag` for
21
21
  writes that do not go through the SDK.
22
+ - Read CI records with `resources.records.get` and `search` (`ServerClient`
23
+ `records.get` and `search` in `/effect`). `knowledge.getEntity` and
24
+ `searchEntities` reject with `TypeError`.
25
+ - In an Effect server that calls CI as each member, build one
26
+ `layerDelegatedServerClient` for the app and provide the member token per
27
+ request as `DelegatedAccessToken`. Do not build a client per token.
22
28
  - Mount the Revalidate Route next to the ticket route, with the same
23
29
  `secrets`.
24
30
  - Branch on an error by its class (`instanceof`, `Effect.catchTag`) and its
@@ -37,5 +43,5 @@ Primitives, the Revalidate Route and the Effect services. The package
37
43
  run when an app caches CI reads with its own tags or revalidates after SDK
38
44
  writes by hand.
39
45
  - [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
46
+ run when code imports a removed subpath or an Effect API outside
41
47
  `/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
@@ -691,10 +687,55 @@ if (slot.ok) {
691
687
  values; a portable resource form has no File field, so
692
688
  `projectResourceSchema` refuses them.
693
689
 
694
- ## Record writes
690
+ ## Records
691
+
692
+ `resources.records` reads, searches, creates, updates and deletes the
693
+ records of an entity schema through CI's resources API.
694
+
695
+ ### Record reads
696
+
697
+ ```ts
698
+ const read = await ci.resources.records.get({
699
+ id: "lead-1",
700
+ include: ["company"],
701
+ organizationId,
702
+ schemaId: "acme.crm.lead"
703
+ })
704
+ const page = await ci.resources.records.search({
705
+ filter: { field: "status", operator: "eq", value: "open" },
706
+ organizationId,
707
+ pagination: { mode: "page", page: 1, pageSize: 20 },
708
+ schemaId: "acme.crm.lead",
709
+ sort: [{ direction: "desc", field: "createdAt" }]
710
+ })
711
+ ```
695
712
 
696
- `resources.records` creates, updates and deletes the records of an entity
697
- schema through CI's resources API.
713
+ - `get` sends `GET /application/v1/resources/:schemaId/records/:id`.
714
+ `include` names Include Paths, such as `["company", "contacts.company"]`.
715
+ The result is the record `{ id, revision, value }`; with `include`, it
716
+ also has `included`, and `truncated` names the keys whose records CI cut
717
+ to the first 100.
718
+ - `search` sends `POST /application/v1/resources/:schemaId/search` with
719
+ only the keys that the request gives: `filter`, `include`, `pagination`,
720
+ `sort` and `textSearch`. The query is the `EntityListQuery` of
721
+ `./resources`: `pagination` is `{ mode: "page", page, pageSize }`, with
722
+ `page >= 1` and `pageSize` from 1 to 100. The result is the page
723
+ `{ items, page, pageSize, pagination: "page", totalItems, totalPages }`
724
+ (`ServerRecordPage`).
725
+ - A read uses the credentials, the `timeoutMs`, the `signal` and the retry
726
+ policy of a write. A read sends no idempotency key. Each attempt sends
727
+ the same correlation id. A refusal resolves `{ ok: false, error }`; an
728
+ answer of CI that is not a record or a page rejects with
729
+ `CiTransportError`.
730
+ - A read asks no schema snapshot, invalidates no cache tag and adds no cache
731
+ tag: the SDK does not cache it. To cache a shared read in Next.js, call
732
+ [`cacheCiRead`](#nextjs-cache-primitives) with the service-mode client in
733
+ the app's `"use cache"` scope.
734
+ - `knowledge.getEntity` and `knowledge.searchEntities` do not reach CI:
735
+ they reject with `TypeError` and point to `/application/v1/resources`.
736
+ Use `resources.records.get` and `resources.records.search`.
737
+
738
+ ### Record writes
698
739
 
699
740
  ```ts
700
741
  const created = await ci.resources.records.create({
@@ -990,9 +1031,16 @@ that reads Effect `Config`:
990
1031
  request)` keeps the CI error envelope as a value; `execute` fails with
991
1032
  `CiError`. A transport failure fails with `CiTransportError`.
992
1033
  `sendMessage` and `createUpload` keep the refusal of CI as a value.
993
- `records.create`, `records.update` and `records.delete`
1034
+ `records.get`, `records.search` ([Record reads](#record-reads)) and
1035
+ `records.create`, `records.update`, `records.delete`
994
1036
  ([Record writes](#record-writes)) fail with `CiError`; `recordsResult`
995
- has the same writes and keeps the refusal of CI as a value.
1037
+ has the same methods and keeps the refusal of CI as a value.
1038
+ - `layerDelegatedServerClient(config)`: one app-wide `ServerClient` that
1039
+ calls CI as the member of each request. `config` is a client config
1040
+ without `authentication`. Each attempt sends the `DelegatedAccessToken` of
1041
+ the calling fiber as `Bearer`; provide it per request. A call on a fiber
1042
+ without one dies with `TypeError` and sends no request. The method types
1043
+ do not change. Use it in place of one client for each member token.
996
1044
  - Without a `sleep` option, the retry backoff of `ServerClient` is
997
1045
  `Effect.sleep` on the Clock: `TestClock` drives it, and an interruption
998
1046
  stops it. With `sleep`, the client waits on that function.
@@ -1030,6 +1078,28 @@ const program = ServerClient.use((client) =>
1030
1078
  )
1031
1079
  ```
1032
1080
 
1081
+ One client for all members, with the token of each request on its fiber:
1082
+
1083
+ ```ts
1084
+ import * as Effect from "effect/Effect"
1085
+ import * as Option from "effect/Option"
1086
+ import {
1087
+ DelegatedAccessToken,
1088
+ layerDelegatedServerClient,
1089
+ ServerClient
1090
+ } from "@collective-intelligence/external-apps-server-sdk/effect"
1091
+
1092
+ // Build the layer once, in the app runtime.
1093
+ const CiLive = layerDelegatedServerClient({
1094
+ tenantUrl: "https://tenant.example"
1095
+ })
1096
+
1097
+ const readLead = (memberToken: string, id: string) =>
1098
+ ServerClient.use((client) =>
1099
+ client.records.get({ id, organizationId, schemaId: "acme.crm.lead" })
1100
+ ).pipe(Effect.provideService(DelegatedAccessToken, Option.some(memberToken)))
1101
+ ```
1102
+
1033
1103
  `DateTimeString` and `UuidV7` provide reusable wire schemas;
1034
1104
  `jsonSchema` projects an Effect schema into the JSON Schema document accepted
1035
1105
  by gateway resource and operation definitions. The projection rejects unknown
@@ -1433,7 +1503,7 @@ Next.js app with `output: "standalone"` gets them in its output without a
1433
1503
  bundler with `Module not found`. A bad pool config or a failed migration fails
1434
1504
  the layer with `DrizzlePostgresInitializationError`.
1435
1505
  `DrizzlePostgres` and `DrizzlePostgresInitializationError` have one identity
1436
- in `/effect`, `/effect/node-postgres` and `/persistence/drizzle/effect`. The
1506
+ in `/effect` and `/effect/node-postgres`. The
1437
1507
  declarations of `/effect` and `/effect/node-postgres` refer to `drizzle-orm`
1438
1508
  and `pg` types: an application that type checks with `skipLibCheck: false`
1439
1509
  installs `drizzle-orm` and `@types/pg`.