@synap-core/sdk 1.4.0 → 1.5.0

package/dist/testing.d.cts

@@ -1,5 +1,5 @@
-import { P as PublicForm, g as PublicShare, e as PublicRecord } from './client-C5sF20f1.cjs';
-import { P as PodGrant, a as PodUser, C as ClientMetadataDocument } from './types-C2KGNXEn.cjs';
+import { P as PublicForm, h as PublicShare, f as PublicRecord } from './client-B50KC2aJ.cjs';
+import { P as PodGrant, a as PodUser, b as PodActsAs, C as ClientMetadataDocument } from './types-DZYNBCq7.cjs';
 
 /**
  * Demo data for the mock pod. Shapes are the `@synap-core/sdk/public` wire
@@ -8,6 +8,12 @@ import { P as PodGrant, a as PodUser, C as ClientMetadataDocument } from './type
 
 declare const MOCK_FORM: PublicForm;
 declare const MOCK_SHARE: PublicShare;
+/**
+ * A published HTML document (an estimate), as the pod serves an `html` body: a
+ * page renders it only inside `<iframe sandbox="" srcdoc>`, so the script below
+ * never runs.
+ */
+declare const MOCK_HTML_SHARE: PublicShare;
 /** One collection of a mock site: its door config and its live records. */
 interface MockCollection {
     /** Default sort keys (`-` = descending); also the sort keys the door accepts. */
@@ -29,6 +35,90 @@ interface MockSite {
  */
 declare const MOCK_SITE: MockSite;
 
+/**
+ * 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).
+ */
+
+interface MockSeedEntity {
+    id: string;
+    profileSlug?: string;
+    workspaceId?: string | null;
+    title?: string | null;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+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;
+}
+interface MockSeedDocument {
+    id: string;
+    title: string;
+    content: string;
+    type?: string;
+    language?: string | null;
+    workspaceId?: string | null;
+    revision?: number;
+    version?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface MockSeedRelation {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    type: string;
+    createdAt?: string;
+}
+interface MockSeedSpace {
+    id: string;
+    name: string;
+    /** The template it came from (e.g. `content-os`); absent = made by hand. */
+    templateSlug?: string;
+}
+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[];
+}
+/**
+ * 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.
+ */
+declare function parseMockPodSeed(input: string | unknown): MockPodSeed;
+
 /** A placeholder pod origin; never contacted. */
 declare const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 declare const MOCK_GRANT: PodGrant[];
@@ -36,7 +126,7 @@ declare const MOCK_USER: PodUser;
 type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
 interface MockAuthServerOptions {
     issuer?: string;
-    /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+    /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
     refresh?: boolean;
     /** Default 3600 (the pod's 1 h). */
     accessTtlSec?: number;
@@ -44,7 +134,7 @@ interface MockAuthServerOptions {
     refreshIdleSec?: number;
     /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
     advertiseRefreshExpiry?: boolean;
-    /** The reuse grace, seconds (PB3b). Default 30 (the pod's); 0 = off (a pod before PB3b). */
+    /** The reuse grace, seconds. Default 30 (the pod's); 0 = off (a pod without the grace). */
     refreshGraceSec?: number;
     /**
      * `synap_app` on token responses: the connection's id and its page on the
@@ -60,8 +150,22 @@ interface MockAuthServerOptions {
     user?: PodUser;
     /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
     metadata?: Record<string, unknown>;
-    /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+    /**
+     * Hub writes: "proposed" (ask-first, the default for an agent token) or
+     * "applied" (the default for `actsAs: "person"`).
+     */
     writeMode?: "proposed" | "applied";
+    /**
+     * `synap_acts_as` on token responses. Omitted = not sent (a pod that does
+     * not name it; the SDK reads an agent connection).
+     */
+    actsAs?: PodActsAs;
+    /**
+     * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
+     * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
+     * those spaces.
+     */
+    seed?: MockPodSeed;
     /** Hub paths (after /api/hub) that answer one failure. */
     failures?: Record<string, MockHubFailure>;
     now?: () => number;
@@ -113,8 +217,10 @@ interface MockAuthServer {
         path: string;
         body: unknown;
     }>;
-    /** Proposals filed by proposed writes, in order. */
+    /** Proposals: the seeded ones, then those filed by proposed writes, in order. */
     proposals: MockProposal[];
+    /** Proposals approved through `POST /proposals/:id/approve`, in order. */
+    approvals: string[];
     /** The person approved or rejected one: it leaves the pending list. */
     settleProposal(id: string, status: "approved" | "rejected"): void;
     /** Another instance of the app rotated `token` (its own refresh): returns the pair the pod answered it. */
@@ -135,30 +241,18 @@ interface MockAuthServer {
     reuses: number;
     /** The person revoked the app: every token stops working. */
     revokeAll(): void;
+    /**
+     * The live access keys stop working, the refresh tokens do not: what a
+     * narrow (the slot's key is revoked at once) or a pod-side "Revoke key"
+     * does. The next refresh mints a new key.
+     */
+    revokeAccessKeys(): void;
     /** Live (unrevoked) refresh tokens. */
     liveRefreshTokens(): string[];
     reset(): void;
 }
 declare function createMockAuthServer(options?: MockAuthServerOptions): MockAuthServer;
 
-/**
- * A mock Synap Cloud pod chooser (Control Plane `GET /connect/pod`, wave C1)
- * for "Continue with Synap Cloud" tests and a kit's mock mode. No network:
- * `choose()` stands in for the person signing in to the CP and picking a pod.
- *
- * Wire behaviour mirrors the CP route (doc 18 §1.1): it accepts only
- * `client_id` (an https CIMD URL; http on loopback only with
- * `allowInsecureLoopback`, for a kit's mock mode on http://localhost) and
- * `state` (`^[A-Za-z0-9._~-]{16,256}$`),
- * takes the return URL from the app's client metadata (`initiate_login_uri`),
- * never from the query, and answers `<initiate_login_uri>?iss=<pod issuer>&state=<state>`.
- * It never sees a code or a token.
- *
- *   const cloud = createMockCloud();
- *   createPodAppAuth({ ...config, cloudUrl: cloud.url });
- *   cloud.choose(location, { pod: mockPod.issuer, metadata: auth.metadata })  → the app's return URL
- */
-
 /** A placeholder Control Plane origin; never contacted. */
 declare const MOCK_CLOUD_URL = "https://cp.mock-synap.test";
 interface MockCloud {
@@ -198,12 +292,12 @@ declare function createMockCloud(options?: {
  * `credentials: "include"` request is refused (it rejects, as a CORS failure
  * does); with `{ browser: true }` a non-safelisted request header is too.
  *
- *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
+ *   tokens MOCK_TOKENS.form / .share / .htmlShare / .site   the demo form, shares (markdown, html) and site
  *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
  *   anything else                               the uniform 404
  *
  * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
- * ./auth-server.ts; Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
+ * ./auth-server.ts, seeded from one JSON shape (`parseMockPodSeed`, ./seed.ts); Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 
 /** A placeholder origin; never contacted. */
@@ -211,6 +305,7 @@ declare const MOCK_POD_URL = "https://mock.synap.invalid";
 declare const MOCK_TOKENS: {
     readonly form: "demo-form";
     readonly share: "demo";
+    readonly htmlShare: "demo-html";
     readonly site: "demo-site";
 };
 /** The `Retry-After` the `rateLimitedRetryAfter` token sends. */
@@ -266,4 +361,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_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 MockProposal, type MockRequest, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod };
+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 };

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
-import { P as PublicForm, g as PublicShare, e as PublicRecord } from './client-C5sF20f1.js';
-import { P as PodGrant, a as PodUser, C as ClientMetadataDocument } from './types-C2KGNXEn.js';
+import { P as PublicForm, h as PublicShare, f as PublicRecord } from './client-B50KC2aJ.js';
+import { P as PodGrant, a as PodUser, b as PodActsAs, C as ClientMetadataDocument } from './types-DZYNBCq7.js';
 
 /**
  * Demo data for the mock pod. Shapes are the `@synap-core/sdk/public` wire
@@ -8,6 +8,12 @@ import { P as PodGrant, a as PodUser, C as ClientMetadataDocument } from './type
 
 declare const MOCK_FORM: PublicForm;
 declare const MOCK_SHARE: PublicShare;
+/**
+ * A published HTML document (an estimate), as the pod serves an `html` body: a
+ * page renders it only inside `<iframe sandbox="" srcdoc>`, so the script below
+ * never runs.
+ */
+declare const MOCK_HTML_SHARE: PublicShare;
 /** One collection of a mock site: its door config and its live records. */
 interface MockCollection {
     /** Default sort keys (`-` = descending); also the sort keys the door accepts. */
@@ -29,6 +35,90 @@ interface MockSite {
  */
 declare const MOCK_SITE: MockSite;
 
+/**
+ * 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).
+ */
+
+interface MockSeedEntity {
+    id: string;
+    profileSlug?: string;
+    workspaceId?: string | null;
+    title?: string | null;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+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;
+}
+interface MockSeedDocument {
+    id: string;
+    title: string;
+    content: string;
+    type?: string;
+    language?: string | null;
+    workspaceId?: string | null;
+    revision?: number;
+    version?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface MockSeedRelation {
+    id: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    type: string;
+    createdAt?: string;
+}
+interface MockSeedSpace {
+    id: string;
+    name: string;
+    /** The template it came from (e.g. `content-os`); absent = made by hand. */
+    templateSlug?: string;
+}
+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[];
+}
+/**
+ * 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.
+ */
+declare function parseMockPodSeed(input: string | unknown): MockPodSeed;
+
 /** A placeholder pod origin; never contacted. */
 declare const MOCK_AUTH_ISSUER = "https://pod.mock-synap.test";
 declare const MOCK_GRANT: PodGrant[];
@@ -36,7 +126,7 @@ declare const MOCK_USER: PodUser;
 type MockHubFailure = "rate_limited" | "forbidden" | "door_unsupported" | "unreachable" | "server" | "unavailable";
 interface MockAuthServerOptions {
     issuer?: string;
-    /** Issue rotating refresh tokens (PB3). Default true; false = a pod before PB3. */
+    /** Issue rotating refresh tokens. Default true; false = a pod without refresh tokens. */
     refresh?: boolean;
     /** Default 3600 (the pod's 1 h). */
     accessTtlSec?: number;
@@ -44,7 +134,7 @@ interface MockAuthServerOptions {
     refreshIdleSec?: number;
     /** Send `refresh_token_expires_in` with each refresh token. Default false (the pod does not say). */
     advertiseRefreshExpiry?: boolean;
-    /** The reuse grace, seconds (PB3b). Default 30 (the pod's); 0 = off (a pod before PB3b). */
+    /** The reuse grace, seconds. Default 30 (the pod's); 0 = off (a pod without the grace). */
     refreshGraceSec?: number;
     /**
      * `synap_app` on token responses: the connection's id and its page on the
@@ -60,8 +150,22 @@ interface MockAuthServerOptions {
     user?: PodUser;
     /** Override or remove (undefined) metadata fields: a pod too old, a lying issuer. */
     metadata?: Record<string, unknown>;
-    /** Hub writes: "proposed" (ask-first, the default for an app) or "applied". */
+    /**
+     * Hub writes: "proposed" (ask-first, the default for an agent token) or
+     * "applied" (the default for `actsAs: "person"`).
+     */
     writeMode?: "proposed" | "applied";
+    /**
+     * `synap_acts_as` on token responses. Omitted = not sent (a pod that does
+     * not name it; the SDK reads an agent connection).
+     */
+    actsAs?: PodActsAs;
+    /**
+     * The pod's data as one JSON shape (`parseMockPodSeed`). `seed.entities` come
+     * before `entities`; `seed.spaces` put a `templateSlug` on the grant rows of
+     * those spaces.
+     */
+    seed?: MockPodSeed;
     /** Hub paths (after /api/hub) that answer one failure. */
     failures?: Record<string, MockHubFailure>;
     now?: () => number;
@@ -113,8 +217,10 @@ interface MockAuthServer {
         path: string;
         body: unknown;
     }>;
-    /** Proposals filed by proposed writes, in order. */
+    /** Proposals: the seeded ones, then those filed by proposed writes, in order. */
     proposals: MockProposal[];
+    /** Proposals approved through `POST /proposals/:id/approve`, in order. */
+    approvals: string[];
     /** The person approved or rejected one: it leaves the pending list. */
     settleProposal(id: string, status: "approved" | "rejected"): void;
     /** Another instance of the app rotated `token` (its own refresh): returns the pair the pod answered it. */
@@ -135,30 +241,18 @@ interface MockAuthServer {
     reuses: number;
     /** The person revoked the app: every token stops working. */
     revokeAll(): void;
+    /**
+     * The live access keys stop working, the refresh tokens do not: what a
+     * narrow (the slot's key is revoked at once) or a pod-side "Revoke key"
+     * does. The next refresh mints a new key.
+     */
+    revokeAccessKeys(): void;
     /** Live (unrevoked) refresh tokens. */
     liveRefreshTokens(): string[];
     reset(): void;
 }
 declare function createMockAuthServer(options?: MockAuthServerOptions): MockAuthServer;
 
-/**
- * A mock Synap Cloud pod chooser (Control Plane `GET /connect/pod`, wave C1)
- * for "Continue with Synap Cloud" tests and a kit's mock mode. No network:
- * `choose()` stands in for the person signing in to the CP and picking a pod.
- *
- * Wire behaviour mirrors the CP route (doc 18 §1.1): it accepts only
- * `client_id` (an https CIMD URL; http on loopback only with
- * `allowInsecureLoopback`, for a kit's mock mode on http://localhost) and
- * `state` (`^[A-Za-z0-9._~-]{16,256}$`),
- * takes the return URL from the app's client metadata (`initiate_login_uri`),
- * never from the query, and answers `<initiate_login_uri>?iss=<pod issuer>&state=<state>`.
- * It never sees a code or a token.
- *
- *   const cloud = createMockCloud();
- *   createPodAppAuth({ ...config, cloudUrl: cloud.url });
- *   cloud.choose(location, { pod: mockPod.issuer, metadata: auth.metadata })  → the app's return URL
- */
-
 /** A placeholder Control Plane origin; never contacted. */
 declare const MOCK_CLOUD_URL = "https://cp.mock-synap.test";
 interface MockCloud {
@@ -198,12 +292,12 @@ declare function createMockCloud(options?: {
  * `credentials: "include"` request is refused (it rejects, as a CORS failure
  * does); with `{ browser: true }` a non-safelisted request header is too.
  *
- *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
+ *   tokens MOCK_TOKENS.form / .share / .htmlShare / .site   the demo form, shares (markdown, html) and site
  *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
  *   anything else                               the uniform 404
  *
  * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
- * ./auth-server.ts; Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
+ * ./auth-server.ts, seeded from one JSON shape (`parseMockPodSeed`, ./seed.ts); Synap Cloud's pod chooser: `createMockCloud()`, ./cloud.ts.
  */
 
 /** A placeholder origin; never contacted. */
@@ -211,6 +305,7 @@ declare const MOCK_POD_URL = "https://mock.synap.invalid";
 declare const MOCK_TOKENS: {
     readonly form: "demo-form";
     readonly share: "demo";
+    readonly htmlShare: "demo-html";
     readonly site: "demo-site";
 };
 /** The `Retry-After` the `rateLimitedRetryAfter` token sends. */
@@ -266,4 +361,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_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 MockProposal, type MockRequest, type MockSite, type MockSubmission, createMockAuthServer, createMockCloud, createMockPod };
+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 };