@collective-intelligence/external-apps-server-sdk 0.1.37 → 0.1.39
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 +114 -14
- package/dist/admin.d.ts +1 -0
- package/dist/{runtime/effect.js → chunks/index-7b0e6810.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.d.ts +5 -1
- package/dist/resources.js +1 -1
- package/dist/runtime/effect.d.ts +137 -106
- package/dist/runtime/nestjs.js +1 -1
- 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
|
|
|
@@ -602,7 +646,8 @@ const slot = await ci.resources.createUpload({
|
|
|
602
646
|
filename: "logo.png",
|
|
603
647
|
mimeType: "image/png",
|
|
604
648
|
organizationId,
|
|
605
|
-
schemaId: "apito.vetrina.schemas.member-company"
|
|
649
|
+
schemaId: "apito.vetrina.schemas.member-company",
|
|
650
|
+
size: logo.byteLength
|
|
606
651
|
})
|
|
607
652
|
if (slot.ok) {
|
|
608
653
|
const { headers, method, uploadId, url } = slot.value.result
|
|
@@ -630,7 +675,7 @@ if (slot.ok) {
|
|
|
630
675
|
`{ id }` (or a File value read before) to keep a file, an ordered array for a
|
|
631
676
|
multiple field, or `null` to remove every file. Omit the key to keep its
|
|
632
677
|
files.
|
|
633
|
-
- `/
|
|
678
|
+
- `/effect` exports the Effect schemas `EntityFileValue` (a File value
|
|
634
679
|
as CI reads return it), `EntityFileWrite` (one file of a write) and
|
|
635
680
|
`EntityFileFieldWrite` (the write form of a File field key). Their types
|
|
636
681
|
equal the client SDK types of the same name. They validate CI entity
|
|
@@ -873,9 +918,60 @@ type CrmModule = ExternalAppModule<{
|
|
|
873
918
|
|
|
874
919
|
## Effect authoring
|
|
875
920
|
|
|
876
|
-
Import
|
|
877
|
-
The executable consumer is tested with `effect@4.1.0`. The package root
|
|
878
|
-
|
|
921
|
+
Import Effect APIs from `/effect`; they use the required `effect` peer.
|
|
922
|
+
The executable consumer is tested with `effect@4.1.0`. The package root is a
|
|
923
|
+
Vanilla Facade over the same Effect Core, so it also loads `effect`. The
|
|
924
|
+
package root and `/effect` share one built chunk: a class that both export,
|
|
925
|
+
such as `MemberSessionExchangeError`, has one identity in the application.
|
|
926
|
+
|
|
927
|
+
`/effect` gives one service for each client, with a `layer` and a `layerConfig`
|
|
928
|
+
that reads Effect `Config`:
|
|
929
|
+
|
|
930
|
+
- `ServerClient`: `layerServerClient(config)`,
|
|
931
|
+
`layerServerClientConfig(config)`, and, for the Confidential Application
|
|
932
|
+
identity, `layerApplicationServerClient(config)` and
|
|
933
|
+
`layerApplicationServerClientConfig(config)`. `executeResult(operationId,
|
|
934
|
+
request)` keeps the CI error envelope as a value; `execute` fails with
|
|
935
|
+
`CiError`. A transport failure fails with `CiTransportError`.
|
|
936
|
+
`sendMessage` and `createUpload` keep the refusal of CI as a value.
|
|
937
|
+
- Without a `sleep` option, the retry backoff of `ServerClient` is
|
|
938
|
+
`Effect.sleep` on the Clock: `TestClock` drives it, and an interruption
|
|
939
|
+
stops it. With `sleep`, the client waits on that function.
|
|
940
|
+
- The `layer…Config` constructors read the client secret with
|
|
941
|
+
`Config.Redacted`: a `Config<string>` secret does not type check. The
|
|
942
|
+
request unwraps the secret where it sends it. `layerServerClient` and
|
|
943
|
+
`layerApplicationServerClient` take a string or a `Redacted` secret.
|
|
944
|
+
- `CiEntities`: `layerCiEntities(options)` and `layerCiEntitiesConfig`.
|
|
945
|
+
`executeResult` keeps each failure as a value of its `ResourceResult`;
|
|
946
|
+
`execute` fails with `CiError` or `CiTransportError`. A `CiEntityBinding`
|
|
947
|
+
holds the `definition`, its `schemaFqn` and its `protocol`: make it once
|
|
948
|
+
with `createEntityProtocol(definition)` of
|
|
949
|
+
`@collective-intelligence/external-apps-client-sdk/resources`.
|
|
950
|
+
- `exchangeMemberSession(request)` is an Effect that fails with
|
|
951
|
+
`MemberSessionExchangeError`, a `Schema.TaggedError`. It is the class of the
|
|
952
|
+
package root.
|
|
953
|
+
|
|
954
|
+
```ts
|
|
955
|
+
import * as Effect from "effect/Effect"
|
|
956
|
+
import {
|
|
957
|
+
layerServerClient,
|
|
958
|
+
ServerClient
|
|
959
|
+
} from "@collective-intelligence/external-apps-server-sdk/effect"
|
|
960
|
+
|
|
961
|
+
const program = ServerClient.use((client) =>
|
|
962
|
+
client.execute("context_get", { organizationId })
|
|
963
|
+
).pipe(
|
|
964
|
+
Effect.catchTag("CiError", (error) => Effect.succeed(error.code)),
|
|
965
|
+
Effect.provide(
|
|
966
|
+
layerServerClient({
|
|
967
|
+
authentication: { getAccessToken: () => memberToken },
|
|
968
|
+
tenantUrl: "https://tenant.example"
|
|
969
|
+
})
|
|
970
|
+
)
|
|
971
|
+
)
|
|
972
|
+
```
|
|
973
|
+
|
|
974
|
+
`DateTimeString` and `UuidV7` provide reusable wire schemas;
|
|
879
975
|
`jsonSchema` projects an Effect schema into the JSON Schema document accepted
|
|
880
976
|
by gateway resource and operation definitions. The projection rejects unknown
|
|
881
977
|
properties for `Schema.Struct` objects while preserving the value
|
|
@@ -896,7 +992,7 @@ import {
|
|
|
896
992
|
jsonSchema,
|
|
897
993
|
makeEffectCrudResource,
|
|
898
994
|
UuidV7
|
|
899
|
-
} from "@collective-intelligence/external-apps-server-sdk/
|
|
995
|
+
} from "@collective-intelligence/external-apps-server-sdk/effect"
|
|
900
996
|
|
|
901
997
|
const leadSchema = Schema.Struct({
|
|
902
998
|
createdAt: DateTimeString,
|
|
@@ -1001,12 +1097,12 @@ owns application shutdown and database cleanup.
|
|
|
1001
1097
|
|
|
1002
1098
|
## Next.js, Web and Express hosting
|
|
1003
1099
|
|
|
1004
|
-
`createResourceNextRouteHandlers` from `/
|
|
1100
|
+
`createResourceNextRouteHandlers` from `/next` wraps the same resource
|
|
1005
1101
|
HTTP handler used by other hosts. In an App Router route such as
|
|
1006
1102
|
`app/api/leads/[...path]/route.ts`, export its method handlers:
|
|
1007
1103
|
|
|
1008
1104
|
```ts
|
|
1009
|
-
import { createResourceNextRouteHandlers } from "@collective-intelligence/external-apps-server-sdk/
|
|
1105
|
+
import { createResourceNextRouteHandlers } from "@collective-intelligence/external-apps-server-sdk/next"
|
|
1010
1106
|
import { leadResource, authorizeApplicationRequest } from "../../../../server"
|
|
1011
1107
|
|
|
1012
1108
|
export const runtime = "nodejs"
|
|
@@ -1114,10 +1210,14 @@ entrypoint also exports the individual store factories for hosts that need
|
|
|
1114
1210
|
custom composition.
|
|
1115
1211
|
|
|
1116
1212
|
Effect applications may import `DrizzlePostgres`, `layerFromDatabase`, and
|
|
1117
|
-
`layerNodePostgres` from
|
|
1118
|
-
`@collective-intelligence/external-apps-server-sdk/persistence/drizzle/effect`.
|
|
1213
|
+
`layerNodePostgres` from `@collective-intelligence/external-apps-server-sdk/effect`.
|
|
1119
1214
|
The Node PostgreSQL layer owns the pool lifetime and accepts an explicit
|
|
1120
|
-
`migrate` hook. It
|
|
1215
|
+
`migrate` hook. It loads the optional `pg` and `drizzle-orm` peers when it
|
|
1216
|
+
builds, so `/effect` loads without them. It never discovers a migration directory or runs hidden DDL.
|
|
1217
|
+
A missing peer, a bad pool config or a failed migration fails the layer with
|
|
1218
|
+
`DrizzlePostgresInitializationError`. The `/effect` declarations refer to
|
|
1219
|
+
`drizzle-orm` and `pg` types: an application that type checks with
|
|
1220
|
+
`skipLibCheck: false` installs `drizzle-orm` and `@types/pg`.
|
|
1121
1221
|
|
|
1122
1222
|
The generic machine resource API retains its explicit hard-delete behavior.
|
|
1123
1223
|
Updates and hard deletes compare and replace the revision atomically. Stale
|
|
@@ -1514,7 +1614,7 @@ explicit resubmission.
|
|
|
1514
1614
|
#### File uploads through the BFF
|
|
1515
1615
|
|
|
1516
1616
|
When the definition declares `capabilities.upload: true`, the handler also
|
|
1517
|
-
accepts `POST {basePath}/uploads` with `{ field, filename, mimeType }`. It calls
|
|
1617
|
+
accepts `POST {basePath}/uploads` with `{ field, filename, mimeType, size }`. It calls
|
|
1518
1618
|
`authorize` with the operation `upload`, then forwards the request with the
|
|
1519
1619
|
verified grant to `/application/v1/resources/{schemaFqn}/uploads`. CI answers
|
|
1520
1620
|
the File upload `{ uploadId, url, method: "PUT", headers }`; the browser PUTs
|
|
@@ -1554,7 +1654,7 @@ It answers `{ ticket, expiresAt, streamUrl }`; `streamUrl` is
|
|
|
1554
1654
|
`tenantUrl`. Without a session it answers 401 before calling CI. CI refusals
|
|
1555
1655
|
keep their status, body, and `Retry-After`: 429 `too_many_connections` at the
|
|
1556
1656
|
per-user connection cap, 503 `unavailable`. Use
|
|
1557
|
-
`createRealtimeTicketHandler` from `/runtime/web` or `/
|
|
1657
|
+
`createRealtimeTicketHandler` from `/runtime/web` or `/next` to mount
|
|
1558
1658
|
the route yourself. The client SDK README documents the browser client.
|
|
1559
1659
|
|
|
1560
1660
|
## Optional local user authentication
|
package/dist/admin.d.ts
CHANGED
|
@@ -377,6 +377,7 @@ declare const KnowledgeFileVisibility: {
|
|
|
377
377
|
export type KnowledgeFileVisibility = typeof KnowledgeFileVisibility[keyof typeof KnowledgeFileVisibility];
|
|
378
378
|
export type KnowledgeFileFieldEntry = {
|
|
379
379
|
accepts: Array<string>;
|
|
380
|
+
maxBytes?: number;
|
|
380
381
|
multiple: boolean;
|
|
381
382
|
};
|
|
382
383
|
export type PackageOperationAccepted = {
|