@collective-intelligence/external-apps-server-sdk 0.1.36 → 0.1.38

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/README.md CHANGED
@@ -22,6 +22,60 @@ subpaths:
22
22
  - `/resources` declares promise-based resource handlers over the portable
23
23
  client resource contract.
24
24
 
25
+ ## Packages and peers
26
+
27
+ `effect` (`^4.1.0`) is a required peer. Install it next to the SDK and keep
28
+ one `effect` version in the application. The SDK depends on
29
+ `@collective-intelligence/external-apps-client-sdk` and
30
+ `@collective-intelligence/extensions-sdk` at the same release and does not
31
+ bundle their JavaScript, so the application has one copy of their error
32
+ classes.
33
+ `/effect` is the Effect export and `/next` is the Next.js export; see
34
+ [Effect authoring](#effect-authoring) and
35
+ [Next.js, Web and Express hosting](#nextjs-web-and-express-hosting).
36
+
37
+ ### Subpath migration
38
+
39
+ Three subpaths are deprecated re-exports for one minor release. Each exports
40
+ the same values as its replacement, so classes and service tags have one
41
+ identity. Each name that a subpath takes from its replacement is marked
42
+ `@deprecated`, and the `ci-solution/effect-subpath` lint rule reports the
43
+ subpaths. The replacements do not export the types of the sibling SDKs that
44
+ the deprecated subpaths kept from 0.1.x: import them from
45
+ `@collective-intelligence/extensions-sdk` or
46
+ `@collective-intelligence/external-apps-client-sdk/resources`.
47
+
48
+ | Deprecated subpath | Import instead |
49
+ | ----------------------------- | -------------- |
50
+ | `/runtime/effect` | `/effect` |
51
+ | `/persistence/drizzle/effect` | `/effect` |
52
+ | `/runtime/next` | `/next` |
53
+
54
+ ### Errors
55
+
56
+ The SDK uses the tagged error classes of
57
+ `@collective-intelligence/external-apps-client-sdk`. The package root and
58
+ `/effect` re-export `CiError`, `CiTransportError` and `FederatedAuthError`;
59
+ they are the same classes, so `instanceof` gives one answer in the
60
+ application.
61
+
62
+ - A CI error envelope stays a value: `{ ok: false, error: { correlationId,
63
+ error } }`.
64
+ - A request that does not reach CI, or an answer that is not readable,
65
+ rejects with `CiTransportError`; `cause` holds the original failure.
66
+ - When the caller aborts through `signal`, the call rejects with
67
+ `signal.reason`.
68
+ - Bad input, such as a bad `tenantUrl` or a body that JSON cannot write,
69
+ throws `TypeError`.
70
+ - `defineCiEntityResource` keeps each failure as a value of its
71
+ `ResourceResult`, with `transport_error` and its `outcome`.
72
+ - `GatewayEffectRuntimeError` is a `Schema.TaggedError`; `new
73
+ GatewayEffectRuntimeError(cause)` keeps its positional form.
74
+
75
+ `createServerClient` and `runAsApplication` return a client with `close()`,
76
+ which disposes the runtime of the client. A call that still runs is
77
+ interrupted.
78
+
25
79
  ## Choose authentication by boundary
26
80
 
27
81
  The SDK has three separate authentication boundaries:
@@ -620,7 +674,7 @@ if (slot.ok) {
620
674
  `{ id }` (or a File value read before) to keep a file, an ordered array for a
621
675
  multiple field, or `null` to remove every file. Omit the key to keep its
622
676
  files.
623
- - `/runtime/effect` exports the Effect schemas `EntityFileValue` (a File value
677
+ - `/effect` exports the Effect schemas `EntityFileValue` (a File value
624
678
  as CI reads return it), `EntityFileWrite` (one file of a write) and
625
679
  `EntityFileFieldWrite` (the write form of a File field key). Their types
626
680
  equal the client SDK types of the same name. They validate CI entity
@@ -863,9 +917,60 @@ type CrmModule = ExternalAppModule<{
863
917
 
864
918
  ## Effect authoring
865
919
 
866
- Install the optional `effect` peer and import helpers from `/runtime/effect`.
867
- The executable consumer is tested with `effect@4.0.1`. Core SDK imports
868
- do not load Effect. `DateTimeString` and `UuidV7` provide reusable wire schemas;
920
+ Import Effect APIs from `/effect`; they use the required `effect` peer.
921
+ The executable consumer is tested with `effect@4.1.0`. The package root is a
922
+ Vanilla Facade over the same Effect Core, so it also loads `effect`. The
923
+ package root and `/effect` share one built chunk: a class that both export,
924
+ such as `MemberSessionExchangeError`, has one identity in the application.
925
+
926
+ `/effect` gives one service for each client, with a `layer` and a `layerConfig`
927
+ that reads Effect `Config`:
928
+
929
+ - `ServerClient`: `layerServerClient(config)`,
930
+ `layerServerClientConfig(config)`, and, for the Confidential Application
931
+ identity, `layerApplicationServerClient(config)` and
932
+ `layerApplicationServerClientConfig(config)`. `executeResult(operationId,
933
+ request)` keeps the CI error envelope as a value; `execute` fails with
934
+ `CiError`. A transport failure fails with `CiTransportError`.
935
+ `sendMessage` and `createUpload` keep the refusal of CI as a value.
936
+ - Without a `sleep` option, the retry backoff of `ServerClient` is
937
+ `Effect.sleep` on the Clock: `TestClock` drives it, and an interruption
938
+ stops it. With `sleep`, the client waits on that function.
939
+ - The `layer…Config` constructors read the client secret with
940
+ `Config.Redacted`: a `Config<string>` secret does not type check. The
941
+ request unwraps the secret where it sends it. `layerServerClient` and
942
+ `layerApplicationServerClient` take a string or a `Redacted` secret.
943
+ - `CiEntities`: `layerCiEntities(options)` and `layerCiEntitiesConfig`.
944
+ `executeResult` keeps each failure as a value of its `ResourceResult`;
945
+ `execute` fails with `CiError` or `CiTransportError`. A `CiEntityBinding`
946
+ holds the `definition`, its `schemaFqn` and its `protocol`: make it once
947
+ with `createEntityProtocol(definition)` of
948
+ `@collective-intelligence/external-apps-client-sdk/resources`.
949
+ - `exchangeMemberSession(request)` is an Effect that fails with
950
+ `MemberSessionExchangeError`, a `Schema.TaggedError`. It is the class of the
951
+ package root.
952
+
953
+ ```ts
954
+ import * as Effect from "effect/Effect"
955
+ import {
956
+ layerServerClient,
957
+ ServerClient
958
+ } from "@collective-intelligence/external-apps-server-sdk/effect"
959
+
960
+ const program = ServerClient.use((client) =>
961
+ client.execute("context_get", { organizationId })
962
+ ).pipe(
963
+ Effect.catchTag("CiError", (error) => Effect.succeed(error.code)),
964
+ Effect.provide(
965
+ layerServerClient({
966
+ authentication: { getAccessToken: () => memberToken },
967
+ tenantUrl: "https://tenant.example"
968
+ })
969
+ )
970
+ )
971
+ ```
972
+
973
+ `DateTimeString` and `UuidV7` provide reusable wire schemas;
869
974
  `jsonSchema` projects an Effect schema into the JSON Schema document accepted
870
975
  by gateway resource and operation definitions. The projection rejects unknown
871
976
  properties for `Schema.Struct` objects while preserving the value
@@ -886,7 +991,7 @@ import {
886
991
  jsonSchema,
887
992
  makeEffectCrudResource,
888
993
  UuidV7
889
- } from "@collective-intelligence/external-apps-server-sdk/runtime/effect"
994
+ } from "@collective-intelligence/external-apps-server-sdk/effect"
890
995
 
891
996
  const leadSchema = Schema.Struct({
892
997
  createdAt: DateTimeString,
@@ -991,12 +1096,12 @@ owns application shutdown and database cleanup.
991
1096
 
992
1097
  ## Next.js, Web and Express hosting
993
1098
 
994
- `createResourceNextRouteHandlers` from `/runtime/next` wraps the same resource
1099
+ `createResourceNextRouteHandlers` from `/next` wraps the same resource
995
1100
  HTTP handler used by other hosts. In an App Router route such as
996
1101
  `app/api/leads/[...path]/route.ts`, export its method handlers:
997
1102
 
998
1103
  ```ts
999
- import { createResourceNextRouteHandlers } from "@collective-intelligence/external-apps-server-sdk/runtime/next"
1104
+ import { createResourceNextRouteHandlers } from "@collective-intelligence/external-apps-server-sdk/next"
1000
1105
  import { leadResource, authorizeApplicationRequest } from "../../../../server"
1001
1106
 
1002
1107
  export const runtime = "nodejs"
@@ -1104,10 +1209,14 @@ entrypoint also exports the individual store factories for hosts that need
1104
1209
  custom composition.
1105
1210
 
1106
1211
  Effect applications may import `DrizzlePostgres`, `layerFromDatabase`, and
1107
- `layerNodePostgres` from
1108
- `@collective-intelligence/external-apps-server-sdk/persistence/drizzle/effect`.
1212
+ `layerNodePostgres` from `@collective-intelligence/external-apps-server-sdk/effect`.
1109
1213
  The Node PostgreSQL layer owns the pool lifetime and accepts an explicit
1110
- `migrate` hook. It never discovers a migration directory or runs hidden DDL.
1214
+ `migrate` hook. It loads the optional `pg` and `drizzle-orm` peers when it
1215
+ builds, so `/effect` loads without them. It never discovers a migration directory or runs hidden DDL.
1216
+ A missing peer, a bad pool config or a failed migration fails the layer with
1217
+ `DrizzlePostgresInitializationError`. The `/effect` declarations refer to
1218
+ `drizzle-orm` and `pg` types: an application that type checks with
1219
+ `skipLibCheck: false` installs `drizzle-orm` and `@types/pg`.
1111
1220
 
1112
1221
  The generic machine resource API retains its explicit hard-delete behavior.
1113
1222
  Updates and hard deletes compare and replace the revision atomically. Stale
@@ -1544,7 +1653,7 @@ It answers `{ ticket, expiresAt, streamUrl }`; `streamUrl` is
1544
1653
  `tenantUrl`. Without a session it answers 401 before calling CI. CI refusals
1545
1654
  keep their status, body, and `Retry-After`: 429 `too_many_connections` at the
1546
1655
  per-user connection cap, 503 `unavailable`. Use
1547
- `createRealtimeTicketHandler` from `/runtime/web` or `/runtime/next` to mount
1656
+ `createRealtimeTicketHandler` from `/runtime/web` or `/next` to mount
1548
1657
  the route yourself. The client SDK README documents the browser client.
1549
1658
 
1550
1659
  ## Optional local user authentication