@collective-intelligence/external-apps-server-sdk 0.2.4 → 0.2.6

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
@@ -74,6 +74,8 @@ error } }`.
74
74
  throws `TypeError`.
75
75
  - `defineCiEntityResource` keeps each failure as a value of its
76
76
  `ResourceResult`, with `transport_error` and its `outcome`.
77
+ - A refusal of `ci.access` rejects with `ServerAccessError`, a
78
+ `Schema.TaggedError` with the HTTP `status` and CI's error `body`.
77
79
  - `GatewayEffectRuntimeError` is a `Schema.TaggedError`; `new
78
80
  GatewayEffectRuntimeError(cause)` keeps its positional form.
79
81
 
@@ -578,7 +580,10 @@ API key as the delegated token. CI authorizes each call with the caller's
578
580
  Tuples: members and invitations need `admin.users`, guests `admin.guests`,
579
581
  grants `admin.grants`, Groups `admin.groups`, and the read-only model
580
582
  `admin.profiles`. A refused call rejects with `ServerAccessError` (`status`
581
- and CI's error `body`). Calls are not retried.
583
+ and CI's error `body`); a request that does not reach CI rejects with
584
+ `CiTransportError`. Calls are not retried. In `/effect`, the same methods
585
+ are `access` of `ServerClient` and fail with `ServerAccessError` or
586
+ `CiTransportError` ([Effect authoring](#effect-authoring)).
582
587
 
583
588
  ```ts
584
589
  const created = await ci.access.members.create({
@@ -1064,7 +1069,11 @@ request)` keeps the CI error envelope as a value; `execute` fails with
1064
1069
  `records.get`, `records.search` ([Record reads](#record-reads)) and
1065
1070
  `records.create`, `records.update`, `records.delete`
1066
1071
  ([Record writes](#record-writes)) fail with `CiError`; `recordsResult`
1067
- has the same methods and keeps the refusal of CI as a value.
1072
+ has the same methods and keeps the refusal of CI as a value. `access`
1073
+ has the methods of `ci.access`
1074
+ ([Members, guests, grants and Groups](#members-guests-grants-and-groups-ciaccess));
1075
+ each fails with `ServerAccessError` or `CiTransportError` and is not
1076
+ retried.
1068
1077
  - `layerDelegatedServerClient(config)`: one app-wide `ServerClient` that
1069
1078
  calls CI as the member of each request. `config` is a client config
1070
1079
  without `authentication`. Each attempt sends the `DelegatedAccessToken` of
@@ -1360,12 +1369,23 @@ export const getLead = async (organizationId: string, entityId: string) => {
1360
1369
  the shared cache.
1361
1370
 
1362
1371
  `ciTag` is the one tag vocabulary of the SDK. Each tag is
1363
- `ci:<kind>:<base64url(sha256(key))>` with kind `s` (schema), `e` (entity) or
1364
- `t` (topic), 48 characters, or `ci:all`. A tag holds no id and no filter
1372
+ `ci:<kind>:<base64url(sha256(key))>` with kind `s` (schema), `l` (list), `e`
1373
+ (entity) or `t` (topic), 48 characters, or `ci:all`. A tag holds no id and no filter
1365
1374
  value in clear text, so it stays within the 256-character limit of Next. The
1366
1375
  hash has no key: a person who knows the possible values of a key can find the
1367
- key of a tag by trial, so a tag is not a secret. `ciTag.topic({ schema })`
1368
- without a filter is the Schema Tag. Tags are `CiTag` strings, a branded type.
1376
+ key of a tag by trial, so a tag is not a secret. Tags are `CiTag` strings, a
1377
+ branded type.
1378
+
1379
+ | Read | Tags that `cacheCiRead` gives it |
1380
+ | ----------------------- | ----------------------------------------------------- |
1381
+ | A get of record `id` | `ci:all`, the Schema Tag, the Entity Tag |
1382
+ | A list without a filter | `ci:all`, the Schema Tag, the List Tag |
1383
+ | A list with a filter | `ci:all`, the Schema Tag, the List Tag, the Topic Tag |
1384
+
1385
+ The Schema Tag (`ciTag.schema(fqn)`) covers every read of a schema. The List
1386
+ Tag (`ciTag.list(fqn)`) covers every list of a schema: a write changes which
1387
+ records a list holds, so it expires the List Tag, but never the get of another
1388
+ record. `ciTag.topic({ schema })` without a filter is the List Tag.
1369
1389
 
1370
1390
  With more than one instance and the built-in in-memory store, an
1371
1391
  invalidation reaches only the instance that receives it; other instances serve
@@ -1376,9 +1396,9 @@ when a realtime change arrives in a tab.
1376
1396
  ### Write invalidation
1377
1397
 
1378
1398
  After CI confirms a write of `resources.records`, the SDK invalidates the
1379
- Entity Tag (`ciTag.entity(fqn, id)`) and the Schema Tag (`ciTag.schema(fqn)`)
1380
- of its record, so the next read recomputes each cached entry that carries
1381
- them. A create, update, delete or restore through the CI entity proxy, which
1399
+ Entity Tag of its record (`ciTag.entity(fqn, id)`) and the List Tag of its
1400
+ schema (`ciTag.list(fqn)`), so the next read recomputes the get of that record
1401
+ and every list of the schema. The gets of other records keep their entries. A create, update, delete or restore through the CI entity proxy, which
1382
1402
  the browser entity hooks use, does the same: `ciResources` of the BFF,
1383
1403
  `createCiResourceMounts`, `defineCiEntityResource` and `CiEntities`. A read,
1384
1404
  and a write that CI refuses or that fails, invalidates nothing. The app does
@@ -2024,9 +2044,11 @@ Give the realtime client of the browser
2024
2044
  `invalid_request`); the client SDK splits a larger delivery into bodies of
2025
2045
  100 changes.
2026
2046
  - For each accepted change it revalidates the Topic Tag
2027
- (`ciTag.topic(topic)`, the Schema Tag for a topic without a filter) and the
2047
+ (`ciTag.topic(topic)`, the List Tag for a topic without a filter) and the
2028
2048
  Entity Tag. `reset: true`, which the client posts after a `reset` or
2029
- `access-changed` event, revalidates the tag of each topic in the token. The
2049
+ `access-changed` event, revalidates for each topic in the token its Schema
2050
+ Tag when the topic has no filter (the missed changes have no ids, so the
2051
+ gets expire too), or its Topic Tag. The
2030
2052
  route never revalidates `ci:all`.
2031
2053
  - It calls `revalidateTag(tag, { expire: 0 })`, so the next read computes the
2032
2054
  entry again. On one instance, the first post for a tag revalidates it at