@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 +7 -1
- package/README.md +87 -17
- package/dist/chunks/{index-mp74xvyn.js → index-48qvvmm0.js} +3 -3
- package/dist/chunks/{index-8yk07eg5.js → index-4z962jdh.js} +2 -2
- package/dist/effect/node-postgres.js +1 -1
- package/dist/effect.d.ts +63 -12
- package/dist/effect.js +1 -1
- package/dist/index.d.ts +49 -7
- package/dist/index.js +1 -1
- package/docs/effect.md +16 -8
- package/docs/next-cache.md +5 -0
- package/package.json +4 -22
- package/skills/server-sdk-move-to-effect/SKILL.md +5 -3
- 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
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
|
|
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
|
-
|
|
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
|
|
@@ -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
|
-
##
|
|
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
|
-
`
|
|
697
|
-
|
|
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.
|
|
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
|
|
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
|
|
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`.
|