@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 +120 -11
- package/dist/chunks/index-zrrnrqkm.js +17 -0
- package/dist/effect.d.ts +1352 -0
- package/dist/effect.js +1 -0
- package/dist/express.d.ts +66 -500
- package/dist/gateway/contracts.d.ts +67 -500
- package/dist/gateway.d.ts +76 -503
- package/dist/gateway.js +1 -2
- package/dist/index.d.ts +89 -53
- package/dist/index.js +1 -16
- package/dist/knowledge-sources/payload.d.ts +31 -187
- package/dist/knowledge-sources/strapi.d.ts +31 -187
- package/dist/next.d.ts +358 -0
- package/dist/next.js +1 -0
- package/dist/persistence/drizzle-effect.d.ts +23 -4
- package/dist/persistence/drizzle.d.ts +51 -196
- package/dist/persistence/drizzle.js +1 -9
- package/dist/resources.d.ts +45 -274
- package/dist/resources.js +4 -11
- package/dist/runtime/effect.d.ts +141 -787
- package/dist/runtime/express.d.ts +66 -500
- package/dist/runtime/nestjs.d.ts +82 -599
- package/dist/runtime/nestjs.js +1 -8
- package/dist/runtime/next.d.ts +130 -606
- package/dist/runtime/web.d.ts +78 -505
- package/dist/runtime/web.js +1 -8
- package/dist/tools/ai-sdk.d.ts +19 -110
- package/dist/tools/ai-sdk.js +1 -2
- package/package.json +26 -14
- package/dist/persistence/drizzle-effect.js +0 -1
- package/dist/runtime/effect.js +0 -16
- package/dist/runtime/next.js +0 -8
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
|
-
- `/
|
|
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
|
-
|
|
867
|
-
The executable consumer is tested with `effect@4.0
|
|
868
|
-
|
|
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/
|
|
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 `/
|
|
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/
|
|
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
|
|
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 `/
|
|
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
|