@synap-core/sdk 1.4.0 → 1.5.1

package/src/testing/seed.ts

@@ -0,0 +1,196 @@
+/**
+ * The mock pod's data as ONE JSON-serialisable shape, so an app's mock mode,
+ * smoke and screenshots replay a recorded snapshot (one file) instead of
+ * fixtures built in app code:
+ *
+ *   import { readFileSync } from "node:fs";
+ *   const seed = parseMockPodSeed(readFileSync("mock/pod-seed.json", "utf8"));
+ *   const pod = createMockAuthServer({ seed });
+ *
+ * Rows are the pod's wire shapes (see `@synap-core/sdk/connect` hub-types):
+ * `entities` as `GET /entities` answers them, `sessions` as `GET
+ * /focus-sessions` rows (missing columns get the pod's defaults), `documents`
+ * as `GET /documents/:id` (`sections` and `diagnostics` answered empty),
+ * `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.
+ */
+import type { MockProposal } from "./auth-server";
+import { desugarSeedRoles } from "./roles";
+
+/** One role an entity wears (backend `FacetRowAnnotation`, plus the space it is stamped in). */
+export 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;
+}
+
+export 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;
+}
+
+export interface MockSeedSession {
+  id: string;
+  workspaceId?: string | null;
+  projectId?: string | null;
+  goal?: string;
+  status?: string;
+  /** Slots; `owner: "human"` ones are what waits on the person. */
+  expectedOutputs?: Array<Record<string, unknown>>;
+  /** The entity it is about: listed among that entity's connections. */
+  subjectEntityId?: string | null;
+  /** ISO 8601; the list is newest first by it. */
+  startedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface MockSeedDocument {
+  id: string;
+  title: string;
+  content: string;
+  type?: string;
+  language?: string | null;
+  workspaceId?: string | null;
+  revision?: number;
+  version?: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export interface MockSeedRelation {
+  id: string;
+  sourceEntityId: string;
+  targetEntityId: string;
+  type: string;
+  createdAt?: string;
+}
+
+export interface MockSeedSpace {
+  id: string;
+  name: string;
+  /** The template it came from (e.g. `content-os`); absent = made by hand. */
+  templateSlug?: string;
+}
+
+export interface MockPodSeed {
+  entities?: MockSeedEntity[];
+  sessions?: MockSeedSession[];
+  documents?: MockSeedDocument[];
+  relations?: MockSeedRelation[];
+  /** Missing fields default to a pending `create` of an `entity`, with null ids and the seed's load time. */
+  proposals?: Array<Partial<MockProposal> & { id: string }>;
+  spaces?: MockSeedSpace[];
+}
+
+const KEYS = ["entities", "sessions", "documents", "relations", "proposals", "spaces"] as const;
+
+/** Required string fields per collection (the rest is free-form, as the pod's rows). */
+const REQUIRED: Record<(typeof KEYS)[number], readonly string[]> = {
+  entities: ["id"],
+  sessions: ["id"],
+  documents: ["id", "title", "content"],
+  relations: ["id", "sourceEntityId", "targetEntityId", "type"],
+  proposals: ["id"],
+  spaces: ["id", "name"],
+};
+
+/**
+ * Read a seed (JSON text or an already-parsed value) and check its shape:
+ * every collection optional, each an array of objects carrying its required
+ * string fields; unknown top-level keys are refused (a typo would otherwise
+ * seed nothing). Throws `TypeError` naming the first bad path.
+ */
+export function parseMockPodSeed(input: string | unknown): MockPodSeed {
+  const value: unknown = typeof input === "string" ? JSON.parse(input) : input;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError("seed: expected an object");
+  const obj = value as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (!(KEYS as readonly string[]).includes(key)) throw new TypeError(`seed.${key}: unknown collection (expected ${KEYS.join(", ")})`);
+  }
+  for (const key of KEYS) {
+    const rows = obj[key];
+    if (rows === undefined) continue;
+    if (!Array.isArray(rows)) throw new TypeError(`seed.${key}: expected an array`);
+    rows.forEach((row, i) => {
+      if (!row || typeof row !== "object" || Array.isArray(row)) throw new TypeError(`seed.${key}[${i}]: expected an object`);
+      for (const field of REQUIRED[key]) {
+        if (typeof (row as Record<string, unknown>)[field] !== "string") throw new TypeError(`seed.${key}[${i}].${field}: expected a string`);
+      }
+      if (key === "entities") checkFacets((row as Record<string, unknown>).facets, `seed.entities[${i}].facets`);
+    });
+  }
+  (obj.entities as Array<Record<string, unknown>> | undefined)?.forEach((row, i) => {
+    const roles = row.seedRoles;
+    if (roles === undefined) 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 as Record<string, unknown>)[field] !== "string") {
+          throw new TypeError(`seed.entities[${i}].seedRoles[${j}].${field}: expected a string`);
+        }
+      }
+    });
+  });
+  // A JSON round trip: what the mock serves is what a file could hold. Then ONE role model: seedRoles → facets.
+  const out = JSON.parse(JSON.stringify(obj)) as MockPodSeed;
+  if (out.entities) out.entities = out.entities.map((row, i) => desugarSeedRoles(row, `seed.entities[${i}]`) as MockSeedEntity);
+  return out;
+}
+
+function checkFacets(facets: unknown, at: string): void {
+  if (facets === undefined) 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 as Record<string, unknown>)[field] !== "string") throw new TypeError(`${at}[${j}].${field}: expected a string`);
+    }
+    const shared = (f as Record<string, unknown>).sharedRole;
+    if (shared !== undefined && typeof shared !== "boolean") throw new TypeError(`${at}[${j}].sharedRole: expected a boolean`);
+  });
+}

package/dist/chunk-J7XHAAFJ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/connect/encoding.ts"],"sourcesContent":["/**\n * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code\n * runs on Node 18+, edge runtimes and workers. No Node import.\n */\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\n/** `Uint8Array<ArrayBuffer>`: what WebCrypto's `BufferSource` takes under TS 5.7+ lib types. */\nexport type Bytes = Uint8Array<ArrayBuffer>;\n\nexport function utf8(text: string): Bytes {\n  return encoder.encode(text);\n}\n\nexport function fromUtf8(bytes: Uint8Array): string {\n  return decoder.decode(bytes);\n}\n\nexport function base64url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Null when `text` is not base64url. */\nexport function fromBase64url(text: string): Bytes | null {\n  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;\n  const padded = text.replace(/-/g, \"+\").replace(/_/g, \"/\") + \"===\".slice((text.length + 3) % 4);\n  let binary: string;\n  try {\n    binary = atob(padded);\n  } catch {\n    return null;\n  }\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\nexport function randomBytes(length: number): Bytes {\n  const out = new Uint8Array(length);\n  crypto.getRandomValues(out);\n  return out;\n}\n\n/** 32 random bytes, base64url (43 chars): a state value or a PKCE verifier. */\nexport function randomToken(): string {\n  return base64url(randomBytes(32));\n}\n\n/** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */\nexport async function pkceChallenge(verifier: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", utf8(verifier));\n  return base64url(new Uint8Array(digest));\n}\n\n/** Compare two strings without an early exit on the first differing byte. */\nexport function constantTimeEqual(a: string, b: string): boolean {\n  const x = utf8(a);\n  const y = utf8(b);\n  let diff = x.length ^ y.length;\n  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);\n  return diff === 0;\n}\n\n/** The request's cookies by name (the first value wins, as browsers order the most specific first). */\nexport function parseCookies(header: string | null): Map<string, string> {\n  const out = new Map<string, string>();\n  if (!header) return out;\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq < 0) continue;\n    const name = part.slice(0, eq).trim();\n    if (!name || out.has(name)) continue;\n    let value = part.slice(eq + 1).trim();\n    if (value.startsWith('\"') && value.endsWith('\"')) value = value.slice(1, -1);\n    out.set(name, value);\n  }\n  return out;\n}\n\nexport interface CookieAttributes {\n  maxAgeSec: number;\n  secure: boolean;\n}\n\n/** `HttpOnly; SameSite=Lax; Path=/` always; `Secure` on https. Never a `Domain`. */\nexport function serializeCookie(name: string, value: string, attrs: CookieAttributes): string {\n  const parts = [`${name}=${value}`, \"Path=/\", \"HttpOnly\", \"SameSite=Lax\", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];\n  if (attrs.secure) parts.push(\"Secure\");\n  return parts.join(\"; \");\n}\n"],"mappings":";AAKA,IAAM,UAAU,IAAI,YAAY;AAChC,IAAM,UAAU,IAAI,YAAY;AAKzB,SAAS,KAAK,MAAqB;AACxC,SAAO,QAAQ,OAAO,IAAI;AAC5B;AAEO,SAAS,SAAS,OAA2B;AAClD,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAEO,SAAS,UAAU,OAA2B;AACnD,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,IAAK,WAAU,OAAO,aAAa,MAAM,CAAC,CAAC;AAC7E,SAAO,KAAK,MAAM,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AAC/E;AAGO,SAAS,cAAc,MAA4B;AACxD,MAAI,CAAC,mBAAmB,KAAK,IAAI,EAAG,QAAO;AAC3C,QAAM,SAAS,KAAK,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG,IAAI,MAAM,OAAO,KAAK,SAAS,KAAK,CAAC;AAC7F,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,MAAM,IAAI,WAAW,OAAO,MAAM;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,KAAI,CAAC,IAAI,OAAO,WAAW,CAAC;AACpE,SAAO;AACT;AAEO,SAAS,YAAY,QAAuB;AACjD,QAAM,MAAM,IAAI,WAAW,MAAM;AACjC,SAAO,gBAAgB,GAAG;AAC1B,SAAO;AACT;AAGO,SAAS,cAAsB;AACpC,SAAO,UAAU,YAAY,EAAE,CAAC;AAClC;AAGA,eAAsB,cAAc,UAAmC;AACrE,QAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK,QAAQ,CAAC;AACnE,SAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC;AAGO,SAAS,kBAAkB,GAAW,GAAoB;AAC/D,QAAM,IAAI,KAAK,CAAC;AAChB,QAAM,IAAI,KAAK,CAAC;AAChB,MAAI,OAAO,EAAE,SAAS,EAAE;AACxB,WAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAK,UAAS,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,KAAK;AACtF,SAAO,SAAS;AAClB;AAGO,SAAS,aAAa,QAA4C;AACvE,QAAM,MAAM,oBAAI,IAAoB;AACpC,MAAI,CAAC,OAAQ,QAAO;AACpB,aAAW,QAAQ,OAAO,MAAM,GAAG,GAAG;AACpC,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,KAAK,EAAG;AACZ,UAAM,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACpC,QAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,EAAG;AAC5B,QAAI,QAAQ,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK;AACpC,QAAI,MAAM,WAAW,GAAG,KAAK,MAAM,SAAS,GAAG,EAAG,SAAQ,MAAM,MAAM,GAAG,EAAE;AAC3E,QAAI,IAAI,MAAM,KAAK;AAAA,EACrB;AACA,SAAO;AACT;AAQO,SAAS,gBAAgB,MAAc,OAAe,OAAiC;AAC5F,QAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,UAAU,YAAY,gBAAgB,WAAW,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE;AAC9H,MAAI,MAAM,OAAQ,OAAM,KAAK,QAAQ;AACrC,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}