@collective-intelligence/external-apps-server-sdk 0.1.37 → 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 +111 -12
- package/dist/{runtime/effect.js → chunks/index-zrrnrqkm.js} +11 -2
- package/dist/effect.d.ts +1349 -0
- package/dist/effect.js +1 -0
- package/dist/gateway.d.ts +9 -3
- package/dist/gateway.js +1 -1
- package/dist/index.d.ts +84 -37
- package/dist/index.js +1 -16
- package/dist/next.d.ts +358 -0
- package/dist/next.js +1 -0
- package/dist/persistence/drizzle-effect.d.ts +23 -4
- package/dist/resources.js +1 -1
- package/dist/runtime/effect.d.ts +137 -106
- package/dist/runtime/next.d.ts +126 -86
- package/dist/runtime/web.d.ts +11 -5
- package/dist/runtime/web.js +1 -1
- package/package.json +20 -11
- package/dist/persistence/drizzle-effect.js +0 -1
- package/dist/runtime/next.js +0 -1
package/README.md
CHANGED
|
@@ -30,7 +30,51 @@ one `effect` version in the application. The SDK depends on
|
|
|
30
30
|
`@collective-intelligence/extensions-sdk` at the same release and does not
|
|
31
31
|
bundle their JavaScript, so the application has one copy of their error
|
|
32
32
|
classes.
|
|
33
|
-
`/effect` is the Effect export
|
|
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.
|
|
34
78
|
|
|
35
79
|
## Choose authentication by boundary
|
|
36
80
|
|
|
@@ -630,7 +674,7 @@ if (slot.ok) {
|
|
|
630
674
|
`{ id }` (or a File value read before) to keep a file, an ordered array for a
|
|
631
675
|
multiple field, or `null` to remove every file. Omit the key to keep its
|
|
632
676
|
files.
|
|
633
|
-
- `/
|
|
677
|
+
- `/effect` exports the Effect schemas `EntityFileValue` (a File value
|
|
634
678
|
as CI reads return it), `EntityFileWrite` (one file of a write) and
|
|
635
679
|
`EntityFileFieldWrite` (the write form of a File field key). Their types
|
|
636
680
|
equal the client SDK types of the same name. They validate CI entity
|
|
@@ -873,9 +917,60 @@ type CrmModule = ExternalAppModule<{
|
|
|
873
917
|
|
|
874
918
|
## Effect authoring
|
|
875
919
|
|
|
876
|
-
Import
|
|
877
|
-
The executable consumer is tested with `effect@4.1.0`. The package root
|
|
878
|
-
|
|
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;
|
|
879
974
|
`jsonSchema` projects an Effect schema into the JSON Schema document accepted
|
|
880
975
|
by gateway resource and operation definitions. The projection rejects unknown
|
|
881
976
|
properties for `Schema.Struct` objects while preserving the value
|
|
@@ -896,7 +991,7 @@ import {
|
|
|
896
991
|
jsonSchema,
|
|
897
992
|
makeEffectCrudResource,
|
|
898
993
|
UuidV7
|
|
899
|
-
} from "@collective-intelligence/external-apps-server-sdk/
|
|
994
|
+
} from "@collective-intelligence/external-apps-server-sdk/effect"
|
|
900
995
|
|
|
901
996
|
const leadSchema = Schema.Struct({
|
|
902
997
|
createdAt: DateTimeString,
|
|
@@ -1001,12 +1096,12 @@ owns application shutdown and database cleanup.
|
|
|
1001
1096
|
|
|
1002
1097
|
## Next.js, Web and Express hosting
|
|
1003
1098
|
|
|
1004
|
-
`createResourceNextRouteHandlers` from `/
|
|
1099
|
+
`createResourceNextRouteHandlers` from `/next` wraps the same resource
|
|
1005
1100
|
HTTP handler used by other hosts. In an App Router route such as
|
|
1006
1101
|
`app/api/leads/[...path]/route.ts`, export its method handlers:
|
|
1007
1102
|
|
|
1008
1103
|
```ts
|
|
1009
|
-
import { createResourceNextRouteHandlers } from "@collective-intelligence/external-apps-server-sdk/
|
|
1104
|
+
import { createResourceNextRouteHandlers } from "@collective-intelligence/external-apps-server-sdk/next"
|
|
1010
1105
|
import { leadResource, authorizeApplicationRequest } from "../../../../server"
|
|
1011
1106
|
|
|
1012
1107
|
export const runtime = "nodejs"
|
|
@@ -1114,10 +1209,14 @@ entrypoint also exports the individual store factories for hosts that need
|
|
|
1114
1209
|
custom composition.
|
|
1115
1210
|
|
|
1116
1211
|
Effect applications may import `DrizzlePostgres`, `layerFromDatabase`, and
|
|
1117
|
-
`layerNodePostgres` from
|
|
1118
|
-
`@collective-intelligence/external-apps-server-sdk/persistence/drizzle/effect`.
|
|
1212
|
+
`layerNodePostgres` from `@collective-intelligence/external-apps-server-sdk/effect`.
|
|
1119
1213
|
The Node PostgreSQL layer owns the pool lifetime and accepts an explicit
|
|
1120
|
-
`migrate` hook. It
|
|
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`.
|
|
1121
1220
|
|
|
1122
1221
|
The generic machine resource API retains its explicit hard-delete behavior.
|
|
1123
1222
|
Updates and hard deletes compare and replace the revision atomically. Stale
|
|
@@ -1554,7 +1653,7 @@ It answers `{ ticket, expiresAt, streamUrl }`; `streamUrl` is
|
|
|
1554
1653
|
`tenantUrl`. Without a session it answers 401 before calling CI. CI refusals
|
|
1555
1654
|
keep their status, body, and `Retry-After`: 429 `too_many_connections` at the
|
|
1556
1655
|
per-user connection cap, 503 `unavailable`. Use
|
|
1557
|
-
`createRealtimeTicketHandler` from `/runtime/web` or `/
|
|
1656
|
+
`createRealtimeTicketHandler` from `/runtime/web` or `/next` to mount
|
|
1558
1657
|
the route yourself. The client SDK README documents the browser client.
|
|
1559
1658
|
|
|
1560
1659
|
## Optional local user authentication
|