@synap-core/sdk 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @synap-core/sdk changelog
 
+## 1.5.1
+
+What a pod app sees of a person's pod, and the roles (Kind + Facets) on it: the
+mock pod models the reach rule and answers roles as the pod does, so an app
+that lists by role (a CRM's leads) shows its pages on mock data; the typed
+client asks for roles; mock mode may ask for the review verbs. Additive, except
+the mock behaviours under "Behaviour changes (mock)".
+
+### `@synap-core/sdk/connect`
+
+- **`listEntities({ facetSlug?, includeFacets? })`**: only the entities wearing
+  a role, and each row's roles on it (`PodEntity.facetSlugs`, `PodEntity.facets:
+  PodEntityFacet[]` = `{ facetId, slug, properties, status }`, present only on a
+  row that wears one). `includeFacets` is sent only when true. It needs a pod
+  with the backend release that adds it to `GET /entities` (synap-backend
+  `feat/hub-entities-include-facets`); until that pod runs, the pod ignores it
+  and the rows come back without roles.
+- **Mock mode may ask for the review verbs**: `buildClientMetadata` (and so
+  `createPodAppAuth`) accepts `proposal.approve` / `proposal.reject` on an http
+  loopback `appUrl` (`localhost`, `127.0.0.1`, `[::1]`), so an app that requests
+  them starts mock mode, smoke and shots. A real pod refuses an http client_id
+  outright (synap-backend `client-id-url.ts`); every other origin is refused
+  as in 1.5.0.
+
+### `@synap-core/sdk/testing`
+
+- **The mock models the pod's reach rule**: `GET /entities`, `GET /entities/:id`
+  and connection neighbours answer rows of a granted space plus pod-wide
+  entities (`workspaceId` null) with a role in a granted space. A pod-wide
+  entity with no role in a granted space, and any row of an ungranted space, is
+  never answered (a miss is the pod's empty 404). Reads need an
+  `entity.*.read` grant in the token's scope.
+- **Seeded roles, one field: `MockSeedEntity.facets`** (`MockSeedFacet`:
+  `facetId`, `slug`, `properties?`, `status?`, and seed-only `workspaceId`: the
+  space whose members see the role, stamped there or a pod-wide facet of a role
+  granted to it). Seed input only: no answer carries them unless `includeFacets`
+  asks. Validated by `parseMockPodSeed`.
+- **`seedRoles`** (`[{ profileSlug, workspaceId }]`), **deprecated: use
+  `facets`; removed in 2.0.** A shorthand desugared into `facets` when the seed
+  is read (a generated `facetId`, no overlay); a role stated in both on one
+  entity is a parse error naming the entity.
+- **`facets[].sharedRole`** (seed only, never served, validated): the role is
+  stored pod-wide and granted to `workspaceId` (default: stamped in it). It
+  differs from a stamped role in `includePodWide=false` on a space lens, and in
+  `GET /entities/:id/facets` (its facet answers `workspaceId` null).
+- **`PATCH /entities/:id` of a pod-wide row** is refused (the mock answers 403;
+  the pod's 403 or 404 is not yet pinned): nothing written, no proposal.
+- **A row of another space T with a role stamped in S** is visible to an app
+  granted S (list and by id), as to a member of S; a shared role does not
+  reach a row of another space.
+- **`GET /entities`** as the pod (`rest/entities.ts`): `includePodWide=false`
+  on a workspace lens drops only the pod-wide rows reached through a SHARED role
+  (the pod keeps those with a role stamped in the space); `facetSlug` filters by a role
+  the read sees: what a member of a granted space sees (a workspace lens, that
+  space's roles only; never a role of a space outside the grant); a
+  `profileSlug` naming a role
+  matches its wearers too; `includeFacets=true` adds `facetSlugs` + `facets` to
+  the rows wearing one.
+- **`GET /entities/:id/facets`**: `{ facets: [{ facet, profile, effectiveProperties }] }`
+  (`getEffectiveFacets` under the token's floor; the mock knows a role by its
+  slug only, so `profile` is `{ id: "profile_<slug>", slug, profileKind: "role" }`
+  and `effectiveProperties` is empty). A miss, or an entity out of reach, is the
+  pod's empty 404.
+- **`GET /entities/:id/connections`**: the far end's `facetSlugs` come from its
+  seeded roles, under the read's `workspaceId` lens.
+- Not mirrored: the mock knows no profile catalog (an undeclared `facetSlug`
+  answers `[]` where the pod answers 404; `facetProfileId` is not read), and it
+  serves neither `q` (the pod refuses it to a space-scoped key, and answers 400
+  to `q` with `includeFacets`) nor `scope=all`.
+- Docs: AGENTS.md, "What a pod app can see and do". Needs a pod with the reach
+  rule (rolling out from 2026-10-23; an older pod returns no pod-wide rows to an app).
+
+### Behaviour changes (mock)
+
+- An entity list without `workspaceId` no longer returns rows of spaces the
+  token was not granted; a pod-wide row is listed only when it has a role in a
+  granted space.
+- `includePodWide=false` on a space lens keeps the pod-wide rows with a role
+  stamped in the space (it dropped every pod-wide row).
+- `GET /entities` and `GET /entities/:id` no longer echo a seed row's
+  `facets` / `facetSlugs` (the pod's `entityToWire` never sends them).
+
 ## 1.5.0
 
 For Content Studio, the first pod app on `@synap-core/sdk/connect`, plus a

package/README.md

@@ -122,6 +122,8 @@ SDK refuses out-of-bounds `offset`/`limit`/`sort` locally, without a request),
 pass `ifNoneMatch` from a browser: the doors allow no cross-origin request header
 but `Content-Type`, so the preflight fails (browsers revalidate on their own).
 
+What a pod app can see and do (spaces, pod-wide people and companies, roles): see [AGENTS.md, "What a pod app can see and do"](./AGENTS.md#what-a-pod-app-can-see-and-do).
+
 ## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0, 1.4.0, 1.5.0)
 
 An app that reads and writes a person's OWN pod connects as an OAuth 2.1 public
@@ -290,6 +292,7 @@ const pod = synap.client(connection);
 // Typed reads: PodResult<T>, the same codes as get/post (expired | unauthorized | forbidden |
 // door_unsupported | not_found | invalid | rate_limited | pod_unreachable | server | …)
 await pod.listEntities({ workspaceId, profileSlug: "post", limit: 1000 }); // PodEntity[]
+await pod.listEntities({ workspaceId, facetSlug: "lead", includeFacets: true }); // the wearers of a role, each with facets
 await pod.getEntity(id);                                                 // PodEntity, not_found on a miss
 await pod.getEntityConnections(id);                                      // { connections, counts }
 await pod.getDocument(documentId);                                       // { content, revision, sections, … }
@@ -390,6 +393,19 @@ const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8")); // {
 const pod = createMockAuthServer({ seed, actsAs: "person" });
 ```
 
+1.5.1: an entity's roles ride on its seed row as `facets`, the shape
+`includeFacets=true` answers, plus the space whose members see it
+(`workspaceId`, seed only). A role in a granted space puts a pod-wide row in the app's reach
+(AGENTS.md, "What a pod app can see and do"). `GET /entities` then filters by
+`facetSlug`, drops a lens's pod-wide rows on `includePodWide: false`, and puts
+`facetSlugs` + `facets` on a row only when asked; `GET /entities/:id/facets` is
+served:
+
+```json
+{ "id": "ent_ada", "profileSlug": "person", "title": "Ada", "workspaceId": null,
+  "facets": [{ "facetId": "fct_1", "slug": "lead", "properties": { "leadStage": "prospect" }, "status": "new", "workspaceId": "ws_crm" }] }
+```
+
 
 ```typescript
 const pod = createMockAuthServer();

package/dist/connect.cjs

@@ -860,7 +860,10 @@ function createPodClient(connection, opts = {}) {
       limit: clamp(opts2.limit, 1, 1e3),
       offset: clamp(opts2.offset, 0, Number.MAX_SAFE_INTEGER),
       sort: opts2.sort,
-      includePodWide: opts2.includePodWide
+      includePodWide: opts2.includePodWide,
+      facetSlug: opts2.facetSlug,
+      // Sent only when asked: the default request stays the 1.5.0 one.
+      includeFacets: opts2.includeFacets ? true : void 0
     }, (data) => Array.isArray(data) ? data.filter(hasId) : null);
   }
   async function getEntity(id) {
@@ -1424,6 +1427,10 @@ var PERMISSION_SEGMENT_RE = /^[a-z0-9][a-z0-9_-]*$/;
 function isSynapAppOrigin(origin) {
   return /^https:\/\/[a-z0-9]([a-z0-9-]*[a-z0-9])?\.synap\.live$/.test(origin);
 }
+function isMockModeOrigin(origin) {
+  const url = new URL(origin);
+  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+}
 function assertAppPermission(permission, origin) {
   const segs = permission.split(".");
   const fail = (why) => {
@@ -1433,7 +1440,7 @@ function assertAppPermission(permission, origin) {
     fail("is not <subject>[.<kind>].<action> in lowercase (no *)");
   }
   if (segs.length === 3 && segs[0] !== "entity") fail(`names a kind, but "${segs[0]}" has none (only entity does)`);
-  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && isSynapAppOrigin(origin)) return;
+  if (SYNAP_APP_REVIEW_PERMISSIONS.includes(permission) && (isSynapAppOrigin(origin) || isMockModeOrigin(origin))) return;
   if (!GRANT_ACTIONS.includes(segs[segs.length - 1])) {
     fail(`asks for "${segs[segs.length - 1]}", which an app cannot be granted (read, create, update, delete)`);
   }