@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 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; it exports nothing yet.
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
- - `/runtime/effect` exports the Effect schemas `EntityFileValue` (a File value
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 helpers from `/runtime/effect`; they use the required `effect` peer.
877
- The executable consumer is tested with `effect@4.1.0`. The package root
878
- does not load Effect. `DateTimeString` and `UuidV7` provide reusable wire schemas;
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/runtime/effect"
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 `/runtime/next` wraps the same resource
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/runtime/next"
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 never discovers a migration directory or runs hidden DDL.
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 `/runtime/next` to mount
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 = {