@synap-core/sdk 1.5.0 → 1.5.1

package/dist/testing.d.cts

@@ -51,14 +51,63 @@ declare const MOCK_SITE: MockSite;
  * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
  * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
  * template (`synap_grant[].templateSlug` on the token response).
+ *
+ * An entity's roles ride on its row as `facets`, the shape `GET /entities?
+ * includeFacets=true` answers them (`{ facetId, slug, properties, status }`),
+ * plus the seed-only space each is stamped in, so a seed row reads like a pod
+ * row read with includeFacets. The mock derives `facetSlugs` and the reach rule
+ * from them and serves neither field unless asked, as the pod.
  */
 
+/** One role an entity wears (backend `FacetRowAnnotation`, plus the space it is stamped in). */
+interface MockSeedFacet {
+    facetId: string;
+    /** The role's slug, e.g. `lead`. */
+    slug: string;
+    /** The facet's overlay properties. Default `{}`. */
+    properties?: Record<string, unknown>;
+    /** Its lifecycle status. Default null. */
+    status?: string | null;
+    /**
+     * Seed only, never served: the space the role is in, i.e. the space whose
+     * members see the facet (stamped there, or a pod-wide facet of a role granted
+     * to it). A role in a granted space puts a pod-wide entity in the app's
+     * reach; a workspace lens sees the roles of that space only.
+     */
+    workspaceId: string;
+    /**
+     * Seed only, never served: the role is SHARED, i.e. stored pod-wide (null
+     * `workspaceId`) and granted to `workspaceId`, which then means "the space it
+     * is granted to". Default false = stamped in `workspaceId`. The pod treats the
+     * two alike for reach, except `includePodWide=false` on a space lens, which
+     * drops a pod-wide row reached only through a shared role.
+     */
+    sharedRole?: boolean;
+}
 interface MockSeedEntity {
     id: string;
     profileSlug?: string;
     workspaceId?: string | null;
     title?: string | null;
     properties?: Record<string, unknown>;
+    /**
+     * The roles (facets) it wears, in the wire shape plus the space each is in
+     * (`MockSeedFacet`). SEED INPUT ONLY: the pod sends them only to
+     * `includeFacets`, and so does the mock. A pod-wide entity (`workspaceId:
+     * null`) with a role in a granted space is readable by the app, as a member
+     * of that space sees it. Absent = none.
+     */
+    facets?: MockSeedFacet[];
+    /**
+     * @deprecated Use `facets`; removed in 2.0. Shorthand for `facets` entries
+     * with no id and no overlay: `parseMockPodSeed` turns each into a facet (a
+     * generated `facetId`, empty properties, a null status). A role stated in
+     * both is refused.
+     */
+    seedRoles?: Array<{
+        profileSlug: string;
+        workspaceId: string;
+    }>;
     [key: string]: unknown;
 }
 interface MockSeedSession {
@@ -361,4 +410,4 @@ interface MockPod {
 }
 declare function createMockPod(options?: MockPodOptions): MockPod;
 
-export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };
+export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedFacet, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };

package/dist/testing.d.ts

@@ -51,14 +51,63 @@ declare const MOCK_SITE: MockSite;
  * `relations` as graph edges for `GET /entities/:id/connections`, `proposals`
  * as `GET /proposals?view=basic` rows, `spaces` name each granted space's
  * template (`synap_grant[].templateSlug` on the token response).
+ *
+ * An entity's roles ride on its row as `facets`, the shape `GET /entities?
+ * includeFacets=true` answers them (`{ facetId, slug, properties, status }`),
+ * plus the seed-only space each is stamped in, so a seed row reads like a pod
+ * row read with includeFacets. The mock derives `facetSlugs` and the reach rule
+ * from them and serves neither field unless asked, as the pod.
  */
 
+/** One role an entity wears (backend `FacetRowAnnotation`, plus the space it is stamped in). */
+interface MockSeedFacet {
+    facetId: string;
+    /** The role's slug, e.g. `lead`. */
+    slug: string;
+    /** The facet's overlay properties. Default `{}`. */
+    properties?: Record<string, unknown>;
+    /** Its lifecycle status. Default null. */
+    status?: string | null;
+    /**
+     * Seed only, never served: the space the role is in, i.e. the space whose
+     * members see the facet (stamped there, or a pod-wide facet of a role granted
+     * to it). A role in a granted space puts a pod-wide entity in the app's
+     * reach; a workspace lens sees the roles of that space only.
+     */
+    workspaceId: string;
+    /**
+     * Seed only, never served: the role is SHARED, i.e. stored pod-wide (null
+     * `workspaceId`) and granted to `workspaceId`, which then means "the space it
+     * is granted to". Default false = stamped in `workspaceId`. The pod treats the
+     * two alike for reach, except `includePodWide=false` on a space lens, which
+     * drops a pod-wide row reached only through a shared role.
+     */
+    sharedRole?: boolean;
+}
 interface MockSeedEntity {
     id: string;
     profileSlug?: string;
     workspaceId?: string | null;
     title?: string | null;
     properties?: Record<string, unknown>;
+    /**
+     * The roles (facets) it wears, in the wire shape plus the space each is in
+     * (`MockSeedFacet`). SEED INPUT ONLY: the pod sends them only to
+     * `includeFacets`, and so does the mock. A pod-wide entity (`workspaceId:
+     * null`) with a role in a granted space is readable by the app, as a member
+     * of that space sees it. Absent = none.
+     */
+    facets?: MockSeedFacet[];
+    /**
+     * @deprecated Use `facets`; removed in 2.0. Shorthand for `facets` entries
+     * with no id and no overlay: `parseMockPodSeed` turns each into a facet (a
+     * generated `facetId`, empty properties, a null status). A role stated in
+     * both is refused.
+     */
+    seedRoles?: Array<{
+        profileSlug: string;
+        workspaceId: string;
+    }>;
     [key: string]: unknown;
 }
 interface MockSeedSession {
@@ -361,4 +410,4 @@ interface MockPod {
 }
 declare function createMockPod(options?: MockPodOptions): MockPod;
 
-export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };
+export { type AuthorizeDecision, MOCK_APP, MOCK_APP_AGENT_ID, MOCK_AUTH_ISSUER, MOCK_CLOUD_URL, MOCK_FAILURE_TOKENS, MOCK_FORM, MOCK_GRANT, MOCK_HTML_SHARE, MOCK_POD_URL, MOCK_RETRY_AFTER_SEC, MOCK_SHARE, MOCK_SITE, MOCK_TOKENS, MOCK_USER, type MockAuthRequest, type MockAuthServer, type MockAuthServerOptions, type MockCloud, type MockCollection, type MockHubFailure, type MockPod, type MockPodOptions, type MockPodSeed, type MockProposal, type MockRequest, type MockSeedDocument, type MockSeedEntity, type MockSeedFacet, type MockSeedRelation, type MockSeedSession, type MockSeedSpace, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod, parseMockPodSeed };

package/dist/testing.js

@@ -120,6 +120,20 @@ var MOCK_SITE = {
   }
 };
 
+// src/testing/roles.ts
+function desugarSeedRoles(row, at) {
+  if (!Array.isArray(row.seedRoles)) return row;
+  const { seedRoles, ...rest } = row;
+  const facets = Array.isArray(row.facets) ? row.facets : [];
+  const shorthand = seedRoles.filter((r) => typeof r?.profileSlug === "string" && typeof r.workspaceId === "string").map((r, i) => ({ facetId: `seedrole_${String(row.id)}_${i}`, slug: r.profileSlug, workspaceId: r.workspaceId }));
+  for (const r of shorthand) {
+    if (facets.some((f) => f?.slug === r.slug && f.workspaceId === r.workspaceId)) {
+      throw new TypeError(`${at} ("${String(row.id)}"): the role "${r.slug}" in ${r.workspaceId} is in both facets and seedRoles; keep it in facets only`);
+    }
+  }
+  return { ...rest, facets: [...facets, ...shorthand] };
+}
+
 // src/testing/auth-server.ts
 var MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 var MOCK_GRANT = [
@@ -153,13 +167,27 @@ function createMockAuthServer(options = {}) {
   const writes = [];
   const proposals = [];
   const seed = options.seed ?? {};
-  const entities = [...seed.entities ?? [], ...options.entities ?? []];
+  const entities = [...seed.entities ?? [], ...options.entities ?? []].map(
+    (e, i) => desugarSeedRoles(e, `entities[${i}]`)
+  );
   const sessions = [...seed.sessions ?? []];
   const documents = [...seed.documents ?? []];
   const relations = [...seed.relations ?? []];
   const templateOf = new Map((seed.spaces ?? []).filter((sp) => sp.templateSlug).map((sp) => [sp.id, sp.templateSlug]));
   const approvals = [];
   const seededAt = new Date(now()).toISOString();
+  const rolesOf = (e) => Array.isArray(e.facets) ? e.facets.filter((f) => typeof f?.slug === "string") : [];
+  function readableEntity(e, spaces, only) {
+    if (typeof e.workspaceId === "string" && spaces.has(e.workspaceId) && (!only || e.workspaceId === only)) return true;
+    return facetsOf(e, spaces, only ?? void 0).some((f) => e.workspaceId == null || !f.sharedRole);
+  }
+  const facetsOf = (e, spaces, lens) => rolesOf(e).filter((f) => typeof f.workspaceId === "string" && spaces.has(f.workspaceId) && (lens === void 0 || f.workspaceId === lens));
+  const facetRow = (f) => ({ facetId: f.facetId, slug: f.slug, properties: f.properties ?? {}, status: f.status ?? null });
+  const entityWire = (e) => {
+    const { facets: _facets, facetSlugs: _facetSlugs, ...wire } = e;
+    return wire;
+  };
+  const readSpaces = (scope) => new Set(grant.filter((g) => /^entity\.(.+\.)?read$/.test(g.permission) && scope.includes(g.permission)).map((g) => g.workspaceId));
   for (const p of seed.proposals ?? []) {
     proposals.push({
       proposalType: "create",
@@ -307,11 +335,12 @@ function createMockAuthServer(options = {}) {
     triage: { pending: false, acceptedAt: null, acceptedBy: null },
     ...s
   });
-  function readSeeded(path, query) {
+  function readSeeded(path, query, scope) {
+    const spaces = readSpaces(scope);
     const conn = /^\/entities\/([^/]+)\/connections$/.exec(path);
     if (conn) {
       const id = decodeURIComponent(conn[1]);
-      const ws = query.get("workspaceId");
+      const ws = query.get("workspaceId") ?? void 0;
       const limit = Math.min(Math.max(Number(query.get("limit") ?? 50) || 50, 1), 200);
       const inLens = (e) => !ws || e.workspaceId === ws || e.workspaceId == null;
       const connections = [];
@@ -320,10 +349,15 @@ function createMockAuthServer(options = {}) {
         const outgoing = r.sourceEntityId === id;
         const otherId = outgoing ? r.targetEntityId : r.sourceEntityId;
         const other = entities.find((e) => e.id === otherId);
-        if (!other || !inLens(other)) continue;
+        if (!other || !inLens(other) || !readableEntity(other, spaces)) continue;
         connections.push({
           entityId: otherId,
-          entity: { ...other, type: other.profileSlug ?? other.type ?? null, facetSlugs: other.facetSlugs ?? [] },
+          // relations.ts: the raw row plus its role slugs under the read's facet lens (a 1.5.0 seed's own facetSlugs otherwise).
+          entity: {
+            ...entityWire(other),
+            type: other.profileSlug ?? other.type ?? null,
+            facetSlugs: rolesOf(other).length > 0 ? facetsOf(other, spaces, ws).map((f) => f.slug) : other.facetSlugs ?? []
+          },
           label: r.type,
           direction: outgoing ? "outgoing" : "incoming",
           source: "graph",
@@ -356,7 +390,39 @@ function createMockAuthServer(options = {}) {
     const entity = /^\/entities\/([^/]+)$/.exec(path);
     if (entity) {
       const found = entities.find((e) => e.id === decodeURIComponent(entity[1]));
-      return found ? json(200, found) : new Response(null, { status: 404 });
+      return found && readableEntity(found, spaces) ? json(200, entityWire(found)) : new Response(null, { status: 404 });
+    }
+    const roles = /^\/entities\/([^/]+)\/facets$/.exec(path);
+    if (roles) {
+      const found = entities.find((e) => e.id === decodeURIComponent(roles[1]));
+      if (!found || !readableEntity(found, spaces)) return new Response(null, { status: 404 });
+      return json(200, {
+        facets: facetsOf(found, spaces).map((f) => ({
+          facet: {
+            id: f.facetId,
+            entityId: found.id,
+            profileId: `profile_${f.slug}`,
+            userId: found.userId ?? user.id,
+            // A stamped facet answers its space; a shared role's facet is stored pod-wide.
+            workspaceId: f.sharedRole ? null : f.workspaceId,
+            contextEntityId: null,
+            status: f.status ?? null,
+            statusCategory: null,
+            properties: f.properties ?? {},
+            metadata: {},
+            createdByKind: null,
+            createdByUserId: null,
+            agentUserId: null,
+            sourceProposalId: null,
+            correlationId: null,
+            createdAt: seededAt,
+            updatedAt: seededAt,
+            deletedAt: null
+          },
+          profile: { id: `profile_${f.slug}`, slug: f.slug, profileKind: "role" },
+          effectiveProperties: []
+        }))
+      });
     }
     const doc = /^\/documents\/([^/]+)$/.exec(path);
     if (doc) {
@@ -422,12 +488,27 @@ function createMockAuthServer(options = {}) {
     }
     if (method === "GET" && path === "/users/me") return json(200, user);
     if (method === "GET" && path === "/entities") {
-      const ws = query.get("workspaceId");
+      const ws = query.get("workspaceId") || void 0;
       const kind = query.get("profileSlug");
+      const role = query.get("facetSlug");
+      const podWide = query.get("includePodWide") !== "false";
+      const withFacets = query.get("includeFacets") === "true";
       const offset = Number(query.get("offset") ?? 0) || 0;
       const limit = Number(query.get("limit") ?? 50) || 50;
-      const rows = entities.filter((e) => (!ws || e.workspaceId === ws) && (!kind || e.profileSlug === kind));
-      return json(200, rows.slice(offset, offset + limit));
+      const spaces = readSpaces(row.scope);
+      const rows = entities.filter((e) => {
+        if (!readableEntity(e, spaces, ws)) return false;
+        if (ws && !podWide && e.workspaceId !== ws && !facetsOf(e, spaces, ws).some((f) => !f.sharedRole)) return false;
+        const slugs = facetsOf(e, spaces, ws).map((f) => f.slug);
+        return (!kind || e.profileSlug === kind || slugs.includes(kind)) && (!role || slugs.includes(role));
+      });
+      return json(
+        200,
+        rows.slice(offset, offset + limit).map((e) => {
+          const facets = withFacets ? facetsOf(e, spaces, ws).map(facetRow) : [];
+          return facets.length > 0 ? { ...entityWire(e), facetSlugs: facets.map((f) => f.slug), facets } : entityWire(e);
+        })
+      );
     }
     if (method === "GET" && path === "/proposals") {
       const readable = new Set(grant.filter((g) => g.permission === "proposal.read" && row.scope.includes(g.permission)).map((g) => g.workspaceId));
@@ -442,7 +523,7 @@ function createMockAuthServer(options = {}) {
       return json(200, { proposals: page, limit, offset, total: rows.length, hasMore: offset + page.length < rows.length });
     }
     if (method === "GET") {
-      const read = readSeeded(path, query);
+      const read = readSeeded(path, query, row.scope);
       if (read) return read;
     }
     const approve = method === "POST" ? /^\/proposals\/([^/]+)\/approve$/.exec(path) : null;
@@ -460,6 +541,11 @@ function createMockAuthServer(options = {}) {
       approvals.push(p.id);
       return json(200, { success: true, proposalId: p.id, proposal: { ...p } });
     }
+    const patched = method === "PATCH" ? /^\/entities\/([^/]+)$/.exec(path) : null;
+    if (patched) {
+      const target = entities.find((e) => e.id === decodeURIComponent(patched[1]));
+      if (target && target.workspaceId == null) return json(403, { error: "grant does not allow" });
+    }
     if (method !== "GET") {
       writes.push({ method, path, body });
       const fields = body && typeof body === "object" ? body : {};
@@ -637,9 +723,36 @@ function parseMockPodSeed(input) {
       for (const field of REQUIRED[key]) {
         if (typeof row[field] !== "string") throw new TypeError(`seed.${key}[${i}].${field}: expected a string`);
       }
+      if (key === "entities") checkFacets(row.facets, `seed.entities[${i}].facets`);
     });
   }
-  return JSON.parse(JSON.stringify(obj));
+  obj.entities?.forEach((row, i) => {
+    const roles = row.seedRoles;
+    if (roles === void 0) return;
+    if (!Array.isArray(roles)) throw new TypeError(`seed.entities[${i}].seedRoles: expected an array`);
+    roles.forEach((r, j) => {
+      for (const field of ["profileSlug", "workspaceId"]) {
+        if (!r || typeof r !== "object" || typeof r[field] !== "string") {
+          throw new TypeError(`seed.entities[${i}].seedRoles[${j}].${field}: expected a string`);
+        }
+      }
+    });
+  });
+  const out = JSON.parse(JSON.stringify(obj));
+  if (out.entities) out.entities = out.entities.map((row, i) => desugarSeedRoles(row, `seed.entities[${i}]`));
+  return out;
+}
+function checkFacets(facets, at) {
+  if (facets === void 0) return;
+  if (!Array.isArray(facets)) throw new TypeError(`${at}: expected an array`);
+  facets.forEach((f, j) => {
+    if (!f || typeof f !== "object" || Array.isArray(f)) throw new TypeError(`${at}[${j}]: expected an object`);
+    for (const field of ["facetId", "slug", "workspaceId"]) {
+      if (typeof f[field] !== "string") throw new TypeError(`${at}[${j}].${field}: expected a string`);
+    }
+    const shared = f.sharedRole;
+    if (shared !== void 0 && typeof shared !== "boolean") throw new TypeError(`${at}[${j}].sharedRole: expected a boolean`);
+  });
 }
 
 // src/testing/cloud.ts