@synap-core/sdk 1.3.0 → 1.5.0

package/dist/connect.d.ts

@@ -1,5 +1,5 @@
-import { b as PodConnection, P as PodGrant, C as ClientMetadataDocument, A as AppRequest, c as PodIssuer } from './types-DpqPNaaa.js';
-export { a as PodUser } from './types-DpqPNaaa.js';
+import { c as PodConnection, P as PodGrant, b as PodActsAs, d as PodSpace, C as ClientMetadataDocument, A as AppRequest, e as PodIssuer } from './types-DZYNBCq7.js';
+export { a as PodUser } from './types-DZYNBCq7.js';
 
 /**
  * The one error type of `@synap-core/sdk/connect`. `code` is the contract a UI
@@ -15,7 +15,7 @@ type ConnectErrorCode =
  | "pod_unreachable"
 /** A Synap pod, but too old for app sign-in (no CIMD, no `iss`, no S256). */
  | "pod_unsupported"
-/** Connecting through Synap Cloud is not available yet. */
+/** Connecting through Synap Cloud is not configured for this app (no Control Plane URL). */
  | "cp_unavailable"
 /** The person said no on the consent screen. */
  | "denied"
@@ -31,6 +31,12 @@ type ConnectErrorCode =
  | "expired"
 /** The pod refused the connection's refresh token while it should still live. */
  | "revoked"
+/**
+ * The pod answered a redirect where it must answer itself (a moved pod
+ * answers 308 from its old name for a while): connect again with its new
+ * address. The new address is never taken from the redirect.
+ */
+ | "pod_moved"
 /** The pod answered something the SDK cannot use. */
  | "server_error";
 declare class ConnectError extends Error {
@@ -49,7 +55,260 @@ declare const CONNECT_ERROR_CODES: readonly ConnectErrorCode[];
 /** Parse an untrusted `?error=` value back into a code (null when unknown). */
 declare function parseConnectErrorCode(value: string | null | undefined): ConnectErrorCode | null;
 
-type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable" | "server";
+/**
+ * Wire shapes of the Hub REST doors `createPodClient`'s typed methods read.
+ *
+ * DRIFT RISK: hand-written from synap-backend main (2026-10-22), each from the
+ * route itself, never from `@synap-core/hub-rest-client` alone:
+ *  - entities: `routers/hub-protocol/rest/entities.ts` (`GET /entities`,
+ *    `GET /entities/:id` → `entityToWire`, `_codecs/entity.ts`
+ *    `WireEntitySchema`; `GET /entities/:id/connections` → `relations.ts`
+ *    `getConnections`, `services/object-graph/entity-connections.ts`);
+ *  - documents: `rest/documents.ts` `GET /documents/:id` →
+ *    `services/document-patch/read-document.ts` `projectAgentDocument`;
+ *  - focus sessions: `rest/focus-sessions.ts` `GET /focus-sessions` (raw rows +
+ *    `triage` + `kind`), slots `services/focus-sessions/update-session.ts`
+ *    `expectedOutputWireSchema`;
+ *  - files: `rest/entities.ts` `GET /files/:id/url` → `file-upload.ts`
+ *    `signFileEntityUrl`;
+ *  - approve: `rest/proposals.ts` `POST /proposals/:id/approve`.
+ * Fields the SDK does not read stay on the objects (index signatures): the pod
+ * sends more than is typed here. The mock pod (`@synap-core/sdk/testing`)
+ * answers these shapes; `src/__tests__/connect.typed.test.ts` drives both.
+ */
+/** One entity, as `GET /entities` and `GET /entities/:id` answer it (`WireEntitySchema`). */
+interface PodEntity {
+    id: string;
+    profileSlug: string;
+    /** Deprecated alias of `profileSlug`, still sent. */
+    type?: string;
+    title?: string | null;
+    preview?: string | null;
+    description?: string | null;
+    properties: Record<string, unknown>;
+    systemData?: Record<string, unknown>;
+    userId: string;
+    workspaceId?: string | null;
+    documentId?: string | null;
+    version?: number;
+    /** ISO 8601. */
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+interface ListEntitiesOptions {
+    /** One granted space. Omitted: every space the connection can read. */
+    workspaceId?: string;
+    /** One kind, e.g. `post`. */
+    profileSlug?: string;
+    /** 1-1000 (the pod's bounds); the pod's default is 20. */
+    limit?: number;
+    offset?: number;
+    /** e.g. `updatedAt:desc`. */
+    sort?: string;
+    /** With `workspaceId`: also the person's pod-wide rows (the pod's default: true). */
+    includePodWide?: boolean;
+}
+type PodConnectionSource = "graph" | "property" | "thread" | "context_channel" | "focus_session";
+/** One edge of `GET /entities/:id/connections` (`EntityConnection`). */
+interface PodEntityConnection {
+    /** The other end: an entity, or the channel / session for those sources. */
+    entityId: string;
+    /** The other entity's row (title, `type` = its kind, workspaceId, facetSlugs, …); null for channels and sessions. */
+    entity: {
+        title?: string | null;
+        type?: string | null;
+        workspaceId?: string | null;
+        facetSlugs?: string[] | null;
+        [key: string]: unknown;
+    } | null;
+    label: string;
+    direction: "outgoing" | "incoming" | "structural";
+    source: PodConnectionSource;
+    relationId?: string;
+    relationType?: string;
+    storedAs?: "link";
+    propertySlug?: string;
+    propertyLabel?: string;
+    channelId?: string;
+    channelRelationshipType?: string;
+    channelTitle?: string | null;
+    channelWorkspaceId?: string | null;
+    focusSessionId?: string;
+    focusSessionGoal?: string;
+    focusSessionStatus?: string;
+    focusSessionWorkspaceId?: string | null;
+    /** ISO 8601, or null (a property link has no date). */
+    createdAt?: string | null;
+    [key: string]: unknown;
+}
+interface PodEntityConnections {
+    connections: PodEntityConnection[];
+    counts: {
+        total: number;
+        graph: number;
+        structural: number;
+        threads: number;
+        contextChannels: number;
+        focusSessions: number;
+    };
+}
+interface GetEntityConnectionsOptions {
+    /** A space lens; omitted = everything the connection can read. */
+    workspaceId?: string;
+    /** Per source, 1-200 (the pod's default: 50). */
+    limit?: number;
+}
+/** A document's top-level section (`listDocumentSections`). */
+interface PodDocumentSection {
+    id: string;
+    /** Who owns it (a person's section is not an agent's to change). */
+    owner: string;
+    title: string | null;
+    author: string | null;
+}
+/** `GET /documents/:id` → `document` (`projectAgentDocument`). */
+interface PodDocument {
+    id: string;
+    title: string;
+    /** `markdown`, `text`, `html`, … */
+    type: string;
+    language: string | null;
+    workspaceId: string | null;
+    format: "raw" | "readable";
+    /** Markdown; `readable` replaces embeds by their fallback text. */
+    content: string;
+    /** Pass back as `baseRevision` on a guarded edit. */
+    revision: number;
+    version: number;
+    sections: PodDocumentSection[];
+    /** What will not render; null when the check could not run (`diagnosticsError`). */
+    diagnostics: unknown[] | null;
+    diagnosticsError?: string;
+    updatedAt: string;
+    createdAt: string;
+    [key: string]: unknown;
+}
+interface GetDocumentOptions {
+    /** `raw` (the stored markdown, the pod's default) or `readable`. */
+    format?: "raw" | "readable";
+}
+/** `focus_sessions.status` (`@synap-core/types/focus-sessions` SESSION_STATUSES). */
+type PodSessionStatus = "active" | "paused" | "forming" | "scheduled" | "closed" | "failed" | "cancelled" | "stale";
+/**
+ * One declared deliverable of a session (`expectedOutputWireSchema`). A slot
+ * with `owner: "human"` is waiting on the person: `blockedReason` and `why` say
+ * for what, `ask` how they can answer (confirm, choose, form, act, provide).
+ */
+interface PodSessionSlot {
+    kind: string;
+    label: string;
+    key?: string;
+    optional?: boolean;
+    status?: "pending" | "done";
+    /** Absent = `agent`. */
+    owner?: "human" | "agent";
+    blockedReason?: string;
+    why?: string;
+    /** ISO 8601, stamped by the pod with `owner: "human"`. */
+    owedSince?: string;
+    /** How the person can answer (`@synap-core/types/ask`), or null. */
+    ask?: unknown;
+    answer?: {
+        text: string;
+        messageId: string | null;
+        answeredBy: string;
+        answeredAt: string;
+        question?: string;
+        value?: unknown;
+        [key: string]: unknown;
+    };
+    retiredAt?: string;
+    [key: string]: unknown;
+}
+/** One row of `GET /focus-sessions`. `expectedOutputs` is always an array here (the SDK drops anything else). */
+interface PodFocusSession {
+    id: string;
+    workspaceId: string | null;
+    projectId: string | null;
+    userId: string;
+    title: string | null;
+    goal: string;
+    status: PodSessionStatus | (string & {});
+    templateId: string | null;
+    expectedOutputs: PodSessionSlot[];
+    channelId: string | null;
+    progress: number | null;
+    currentStage: string | null;
+    agentIds: string[];
+    closedAt: string | null;
+    metadata: unknown;
+    startedAt: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Projected by the list door: `work`, `run` (a playbook or automation ran it) or `receipt`. */
+    kind?: "work" | "run" | "receipt";
+    /** Projected by the list door: an agent-started session the person has not accepted yet. */
+    triage?: {
+        pending: boolean;
+        acceptedAt: string | null;
+        acceptedBy: string | null;
+    };
+    [key: string]: unknown;
+}
+interface ListFocusSessionsOptions {
+    /** A space; `workspaceId` or `projectId` is required (the pod's rule). */
+    workspaceId?: string;
+    projectId?: string;
+    /** Default `all` (the pod's default on this door). */
+    status?: PodSessionStatus | "all";
+    /** 1-50 (the pod's bounds); the pod's default is 20. */
+    limit?: number;
+    /** Triage lens: `all` (default here), `default` (hides unaccepted agent sessions), `triage`. */
+    lens?: "all" | "default" | "triage";
+    /** Population lens: `all` (default here), `work`, `run`, `receipt`. */
+    kind?: "all" | "work" | "run" | "receipt";
+    /** Sessions about one thing. */
+    subjectEntityId?: string;
+}
+/** `GET /files/:id/url`: a signed GET for a file entity's blob. */
+interface PodFileUrl {
+    /** Served as an `attachment`, with the stored type. */
+    url: string;
+    /** ISO 8601; the signature's end (about an hour). */
+    expiresAt: string;
+    /** Decide drawability on this, never on the URL; null when unknown. */
+    mimeType: string | null;
+}
+/** `POST /proposals/:id/approve`. */
+interface PodApproval {
+    proposalId: string;
+    /** The row the approval produced or linked, when it names one. */
+    primaryId?: string;
+    linked?: number;
+    /** The proposal after the approval (status, execution result), when the pod could read it back. */
+    proposal: Record<string, unknown> | null;
+}
+interface ApproveProposalOptions {
+    /**
+     * The proposal's space, when known: refused locally unless the connection
+     * holds `proposal.approve` there. Omitted: needs it in some space, and the
+     * pod checks the proposal's own space.
+     */
+    workspaceId?: string;
+}
+
+type PodErrorCode = "expired" | "unauthorized" | "forbidden" | "door_unsupported" | "not_found" | "invalid" | "conflict" | "rate_limited" | "pod_unreachable"
+/** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
+ | "pod_moved" | "server";
+/**
+ * Why the SDK refused before sending anything (`status: null`):
+ *  - `agent_cannot_approve`: an agent connection asked to approve (the pod
+ *    never lets an agent credential approve; `code: "forbidden"`);
+ *  - `not_granted`: the connection holds no permission for it (`forbidden`);
+ *  - `invalid_input`: an id, a path or an option the pod would refuse (`invalid`).
+ */
+type PodRefusalReason = "agent_cannot_approve" | "not_granted" | "invalid_input";
 interface PodError {
     code: PodErrorCode;
     /** The HTTP status, or null when nothing was answered. */
@@ -57,6 +316,17 @@ interface PodError {
     retryAfterSec?: number;
     /** The pod's own error text, for logs only. */
     detail?: string;
+    /** Set when the SDK refused locally (1.5). */
+    reason?: PodRefusalReason;
+    /**
+     * On `unauthorized` (1.5): the pod refused the access token, the connection
+     * still holds a refresh token, and this client could not renew it (no
+     * `renew`). A forced refresh may restore it (a narrow, or a pod-side "Revoke
+     * key", ends the key, not the connection): run `refreshIfNeeded(request,
+     * { force: true })` where cookies can be set. Absent = the pod refused the
+     * connection itself: connect again.
+     */
+    refreshable?: true;
 }
 type PodResult<T> = {
     ok: true;
@@ -80,24 +350,121 @@ type PodWriteResult<T> = {
     error: PodError;
 };
 type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+/** One pending proposal, the pod's summary row (`GET /proposals?view=basic`). */
+interface PendingProposal {
+    id: string;
+    proposalType: string;
+    targetType: string;
+    targetId: string | null;
+    workspaceId: string | null;
+    /** ISO 8601, as the pod sent it. */
+    createdAt: string;
+    /** The agent that filed it (this app's agent, or another one), when known. */
+    agentUserId: string | null;
+    sessionId: string | null;
+    summary?: string;
+    /** Where the person reviews it: the pod's deep link. */
+    reviewUrl: string;
+}
+interface PendingProposals {
+    /** Every pending proposal the connection can see, not only this page (the pod COUNTs it). */
+    total: number;
+    proposals: PendingProposal[];
+    hasMore: boolean;
+}
+interface ListPendingProposalsOptions {
+    /** One granted space only. */
+    workspaceId?: string;
+    /** 1-200, default 20. */
+    limit?: number;
+    offset?: number;
+    /**
+     * Only these proposals (at most 100 ids; the pod's `proposalIds` filter,
+     * pods that do not filter are filtered here). An empty list matches nothing (answered without a request).
+     */
+    proposalIds?: readonly string[];
+}
 interface PodClientOptions {
     fetch?: typeof fetch;
     now?: () => number;
+    /** Per Hub request, default 10 000 ms; a request past it is `pod_unreachable`. */
+    timeoutMs?: number;
+    /** The most a Hub answer may weigh, default 8 MiB; a bigger one is `server` (the body is not read further). */
+    maxResponseBytes?: number;
+    /**
+     * Renew the connection after the pod refused its access token (401) while it
+     * holds a refresh token: rotate it, PERSIST the result (the old refresh token
+     * is spent once the pod answers), then return it; throw the refresh's
+     * `ConnectError` when it fails. The client calls it at most once (concurrent
+     * 401s share the call), retries the refused request once with the result, and
+     * uses it from then on. `PodAppAuth.client(connection, { persist })` builds
+     * one. Without it a 401 stays `unauthorized` (with `refreshable`).
+     */
+    renew?: (connection: PodConnection) => Promise<PodConnection>;
 }
 interface PodClient {
     podUrl: string;
-    user: PodConnection["user"];
-    grant: PodGrant[];
+    /** The connection's, or the renewed one's after a 401 (`renew`). */
+    readonly user: PodConnection["user"];
+    readonly grant: PodGrant[];
+    /** Who the token acts as (`connectionActsAs`): `"agent"` unless the pod said `"person"`. */
+    readonly actsAs: PodActsAs;
     /** Whether the connection was granted `permission` (in `workspaceId` when given). */
     can(permission: string, workspaceId?: string): boolean;
+    /** The granted spaces, each with its permissions (`spaces(connection)`). */
+    spaces(): PodSpace[];
+    /**
+     * "Waiting for review: N". The person's pending proposals in the spaces this
+     * connection may read proposals in (any agent's, not only this app's), from
+     * the pod's seamed `GET /proposals` door. Needs the `proposal.read`
+     * permission (ask for it in `requests`): without it the pod would answer an
+     * empty list, so this answers `forbidden` instead, without a request.
+     */
+    listPendingProposals(opts?: ListPendingProposalsOptions): Promise<PodResult<PendingProposals>>;
+    /** `GET /entities` (no full-text `q`: a space-scoped token may list, never search). */
+    listEntities(opts?: ListEntitiesOptions): Promise<PodResult<PodEntity[]>>;
+    /** `GET /entities/:id`; `not_found` when it does not exist or is not readable. */
+    getEntity(id: string): Promise<PodResult<PodEntity>>;
+    /** `GET /entities/:id/connections`: its relations, property links, threads and sessions. */
+    getEntityConnections(id: string, opts?: GetEntityConnectionsOptions): Promise<PodResult<PodEntityConnections>>;
+    /** `GET /documents/:id`: content, revision, sections. */
+    getDocument(id: string, opts?: GetDocumentOptions): Promise<PodResult<PodDocument>>;
+    /**
+     * `GET /focus-sessions` in a space (or a project), newest first, with their
+     * slots (`expectedOutputs`; `humanSlots(session)` = what waits on the person).
+     * `invalid` without a request when neither `workspaceId` nor `projectId` is given.
+     */
+    listFocusSessions(opts: ListFocusSessionsOptions): Promise<PodResult<PodFocusSession[]>>;
+    /** `GET /files/:id/url`: a signed download URL for a file entity (about an hour). */
+    getFileUrl(entityId: string): Promise<PodResult<PodFileUrl>>;
+    /**
+     * `POST /proposals/:id/approve`, as the person. Only a PERSON connection
+     * (`actsAs: "person"`) holding `proposal.approve` can: an agent connection
+     * gets `forbidden` / `agent_cannot_approve` and NOTHING is sent (the pod
+     * never lets an agent approve); without the permission, `forbidden` /
+     * `not_granted`, also without a request.
+     */
+    approveProposal(id: string, opts?: ApproveProposalOptions): Promise<PodResult<PodApproval>>;
     get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
     post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
     patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
     put<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
     delete<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
 }
+/** Who `connection`'s token acts as: `"person"` only when the pod said so, else `"agent"`. */
+declare function connectionActsAs(connection: Pick<PodConnection, "actsAs">): PodActsAs;
+/**
+ * The slots of `session` that wait on the person (Home's "needs you"):
+ * `owner: "human"`, not done, not retired.
+ */
+declare function humanSlots(session: Pick<PodFocusSession, "expectedOutputs">): PodSessionSlot[];
 /** Whether `connection` was granted `permission` (in `workspaceId` when given). Exact match: grants carry no wildcard. */
 declare function can(connection: Pick<PodConnection, "grant">, permission: string, workspaceId?: string): boolean;
+/**
+ * The grant by space, in the grant's order, each permission once. The pod
+ * sends one row per permission per space; a space switcher wants one per space.
+ */
+declare function spaces(connection: Pick<PodConnection, "grant">): PodSpace[];
 /**
  * Where to review a proposal: the pod's answer, resolved against the pod and
  * kept only on the pod's own origin; else the pod's deep link `/open/<id>`.
@@ -105,7 +472,7 @@ declare function can(connection: Pick<PodConnection, "grant">, permission: strin
 declare function reviewUrlFor(podUrl: string, reviewUrl: unknown, proposalId: string | null): string;
 declare function createPodClient(connection: PodConnection, opts?: PodClientOptions): PodClient;
 
-type SealPurpose = "synap-connect/transaction" | "synap-connect/session";
+type SealPurpose = "synap-connect/transaction" | "synap-connect/session" | "synap-connect/cloud";
 /** The app secret: one value, or several to rotate (the first seals, all open). */
 type AppSecret = string | readonly string[];
 declare const MIN_SECRET_LENGTH = 32;
@@ -143,9 +510,32 @@ interface ConnectionStore {
 interface CookieNames {
     session: string;
     transaction: string;
+    /** A Synap Cloud sign-in in progress (sealed state, 10 minutes). */
+    cloud: string;
+    /** "This browser was connected to <pod>": the pod's URL only, no secret (`markerCookie`). */
+    marker: string;
 }
 /** `__Host-` names on https (Secure, Path=/, no Domain: bound to this exact host). */
 declare function cookieNames(secure: boolean): CookieNames;
+/** The marker outlives the connection: as long as browsers keep a cookie (400 days). */
+declare const MARKER_TTL_SEC: number;
+/**
+ * The marker cookie: which pod this browser was connected to, so a connection
+ * that lapsed (idle past the refresh token's life, its sealed cookie gone)
+ * reads as "expired, connect again to <pod>" rather than "never connected".
+ * It holds the pod's public URL and NOTHING else: no token, no user, nothing
+ * sealed. A forged value can only pre-fill the address the person confirms.
+ */
+declare function markerCookie(podUrl: string, opts: {
+    secure: boolean;
+    name?: string;
+}): string;
+/** The marker's pod URL, or null (absent, or not a canonical pod address). */
+declare function readMarker(cookieHeader: string | null, opts: {
+    secure: boolean;
+    name?: string;
+    allowInsecureLoopback?: boolean;
+}): string | null;
 /** When the stored value stops being useful. */
 declare function connectionExpiresAt(c: PodConnection): number;
 interface SealedCookieStoreOptions {
@@ -169,6 +559,8 @@ interface PodAppPaths {
     connect: string;
     callback: string;
     disconnect: string;
+    /** Synap Cloud: POST starts it, GET is the pod chooser's return (forwarded from the connect page). */
+    cloud: string;
     /** The app's connect page (also the CIMD `initiate_login_uri`). */
     connectPage: string;
     /** Where a failed callback lands, with `?error=<code>`. */
@@ -180,7 +572,12 @@ declare const DEFAULT_PATHS: PodAppPaths;
 /** Refresh only inside the last 5 minutes of the access token's life. */
 declare const REFRESH_WINDOW_MS: number;
 interface PodAppAuthConfig {
-    /** The app's origin, e.g. https://studio.example.com (http only on localhost). */
+    /**
+     * The app's origin, e.g. https://studio.example.com. `http://localhost` is
+     * accepted for the SDK's MOCK pod only: every real pod, a local one
+     * included, refuses an http client_id and redirect_uri, so an app that signs
+     * in to a real pod runs on https (a tunnel in development).
+     */
     appUrl: string;
     /** Shown on the pod's consent screen (at most 100 characters). */
     clientName: string;
@@ -195,7 +592,16 @@ interface PodAppAuthConfig {
     store?: ConnectionStore;
     /** RFC 8707 resource asked for (default the Hub API). */
     resource?: "api/hub" | "mcp" | null;
-    /** Accept pods on http://localhost (development against a local pod). */
+    /**
+     * The Synap Control Plane's URL (e.g. https://api.synap.live): offers
+     * "Continue with Synap Cloud" (`cloudConnectAvailable`). Unset = address only.
+     */
+    cloudUrl?: string | null;
+    /**
+     * Accept a pod (and a Control Plane) on http://localhost: development
+     * against the SDK's mock pod (`@synap-core/sdk/testing`). A real local pod
+     * still refuses an app that is not on https (see `appUrl`).
+     */
     allowInsecureLoopback?: boolean;
     /** Developer log of every refused sign-in; messages never carry a token. Default: console.warn. */
     onError?: (error: ConnectError, where: "connect" | "callback" | "disconnect" | "refresh") => void;
@@ -213,9 +619,9 @@ type RefreshStatus =
  | "refreshed"
 /** The refresh failed (a lost rotation race, the pod busy) but the access token still works: keep it, set nothing. */
  | "kept"
-/** The access token is spent and cannot be renewed: connect again. */
+/** The access token is spent and cannot be renewed (lapsed, or the pod moved: `error.code`): connect again. The session cookie is cleared (the marker stays). */
  | "expired"
-/** The pod refused the refresh token (access removed): connect again. */
+/** The pod refused the refresh token (access removed): connect again. The session cookie is cleared (the marker stays). */
  | "revoked"
 /** The pod could not be reached and the access token is spent: try later. */
  | "unavailable";
@@ -228,17 +634,53 @@ interface RefreshOutcome {
     /** The request's Cookie header with the refreshed value, to forward to the render (null = unchanged). */
     cookieHeader: string | null;
     error?: ConnectError;
+    /**
+     * With `none`: this browser WAS connected to that pod and the connection
+     * lapsed (its sealed cookie is gone, idle past its life). Say "expired,
+     * connect again" with the pod pre-filled, not "connect your pod".
+     */
+    lapsed?: {
+        podUrl: string;
+    };
+}
+interface RefreshOptions {
+    /**
+     * Rotate now, whatever the access token's expiry says: the pod refused it
+     * (a Hub call answered `unauthorized` with `refreshable`). Needs a refresh
+     * token. If the pod refuses the refresh too, the outcome is `revoked` (or
+     * `expired`), never `kept`: the access token is known dead.
+     */
+    force?: boolean;
+}
+interface PodAppClientOptions extends PodClientOptions {
+    /**
+     * Where the client may set cookies (a route handler, a server action): after
+     * a 401 it then renews the connection ONCE (rotate, seal, `persist` the
+     * Set-Cookie values, retry the request once). The rotation spends the old
+     * refresh token, so it is never done where its result cannot be stored: a
+     * server component passes no `persist`, and a 401 there answers
+     * `unauthorized` with `refreshable` (see `RefreshOptions.force`).
+     */
+    persist?: (setCookies: string[]) => void | Promise<void>;
+    /** The request (or its Cookie header) the connection came from: chunks a larger old cookie left are cleared. */
+    request?: Request | string | null;
 }
 interface PodAppAuth {
     clientId: string;
     redirectUri: string;
     metadata: ClientMetadataDocument;
     paths: PodAppPaths;
+    /** Whether "Continue with Synap Cloud" can be offered (`cloudUrl` is configured). */
+    cloudConnectAvailable: boolean;
     handlers: {
         clientMetadata(request: Request): Promise<Response>;
         connect(request: Request): Promise<Response>;
         callback(request: Request): Promise<Response>;
         disconnect(request: Request): Promise<Response>;
+        /** POST: start a Synap Cloud sign-in (same-origin, form { next?, space?, prompt? }). */
+        cloudConnect(request: Request): Promise<Response>;
+        /** GET: the Synap Cloud pod chooser's return (`?iss&state`), checked against this browser's cookie. */
+        cloudReturn(request: Request): Promise<Response>;
     };
     /**
      * The stored connection (no refresh, no expiry check), or null. Takes the
@@ -246,12 +688,25 @@ interface PodAppAuth {
      * pass `(await headers()).get("cookie")`).
      */
     readConnection(source: Request | string | null): Promise<PodConnection | null>;
-    /** For `proxy.ts` / a route handler: rotate near expiry, lost-race safe. */
-    refreshIfNeeded(request: Request): Promise<RefreshOutcome>;
-    /** A Hub REST client for the connection. */
-    client(connection: PodConnection, opts?: PodClientOptions): PodClient;
+    /**
+     * The pod this browser WAS connected to, when no connection is stored any
+     * more (it lapsed); null when one is stored or this browser never connected
+     * (or disconnected). Same sources as `readConnection`.
+     */
+    readLapsed(source: Request | string | null): Promise<{
+        podUrl: string;
+    } | null>;
+    /** For `proxy.ts` / a route handler: rotate near expiry (or now, `force`), lost-race safe. */
+    refreshIfNeeded(request: Request, opts?: RefreshOptions): Promise<RefreshOutcome>;
+    /** A Hub REST client for the connection (renewing it after a 401 when it can `persist`). */
+    client(connection: PodConnection, opts?: PodAppClientOptions): PodClient;
 }
-/** The CIMD document (spec 17 §6.1), validated the way the pod will validate it. */
+/**
+ * The app's client metadata document (its client_id URL serves it). Refuses,
+ * at setup, every document the pod would refuse at sign-in: the permissions
+ * (`assertAppPermission`), at most 32 requests counted as sent, duplicates
+ * included, an IP address origin, the 5 KB cap.
+ */
 declare function buildClientMetadata(opts: {
     appUrl: string;
     clientName: string;
@@ -259,6 +714,21 @@ declare function buildClientMetadata(opts: {
     templates?: readonly string[];
     paths?: Partial<PodAppPaths>;
 }): ClientMetadataDocument;
+/**
+ * A prefetch or a static asset: `refreshIfNeeded` answers `skipped` for these.
+ *
+ * LIMIT (Next.js 16 `proxy.ts` on the Node runtime): Next strips its router
+ * headers (`next-router-prefetch`, `rsc`, …, `FLIGHT_HEADERS` in
+ * next/dist/server/web/adapter.js) and the `_rsc` query BEFORE the proxy runs,
+ * so a router prefetch is invisible here. Skip prefetches in the proxy
+ * MATCHER, which still sees the raw headers:
+ *
+ *   export const config = { matcher: [{ source: "/((?!_next/static|_next/image|.*\\.\\w+$).*)",
+ *     missing: [{ type: "header", key: "next-router-prefetch" }, { type: "header", key: "purpose", value: "prefetch" }] }] };
+ *
+ * Route handlers and other frameworks see the headers, and this still checks them.
+ */
+declare function isPrefetchOrAsset(request: Request): boolean;
 declare function createPodAppAuth(config: PodAppAuthConfig): PodAppAuth;
 
 interface DiscoverOptions {
@@ -276,17 +746,13 @@ declare function canonicalPodUrl(input: string, opts?: {
 }): string;
 /**
  * A typed pod address (or a launch `iss`) → its validated authorization server.
- * Tries the address, then `pod.<host>` (so "antoine.synap.live" finds
- * "pod.antoine.synap.live").
+ * Tries the address, then the pod names it may stand for: on Synap Cloud,
+ * "you.synap.live" finds "you.pod.synap.live" (and the older
+ * "pod.you.synap.live"); elsewhere, "example.com" finds "pod.example.com".
+ * A redirect is never followed: an old name that answers 308 counts as a
+ * miss (`pod_moved` when nothing else answers).
  */
 declare function discoverPod(input: string, opts?: DiscoverOptions): Promise<PodIssuer>;
-/** Whether "Continue with Synap Cloud" can be offered. False until the CP pod chooser (C1) ships. */
-declare function cloudConnectAvailable(): boolean;
-/** The Synap Cloud pod chooser (C1). Not available yet: always throws `cp_unavailable`. */
-declare function startCloudConnect(_opts: {
-    clientId: string;
-    state?: string;
-}): never;
 /**
  * A same-origin path to return to after connecting, or null. Accepts a
  * relative path (never `//host` or `/\host`) or an absolute URL on the app's
@@ -294,25 +760,126 @@ declare function startCloudConnect(_opts: {
  */
 declare function safeNextPath(value: string | null | undefined, appOrigin: string): string | null;
 interface LaunchHint {
-    /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM (T6), never to auto-connect. */
+    /** The pod issuer the launcher named (`iss`), to pre-fill and CONFIRM, never to auto-connect. */
     pod: string | null;
     /** Where to land after connecting (`target_link_uri`), same origin only. */
     next: string | null;
-    /** A space to preselect on consent (`synap_space_hint`). */
+    /** A space hint for the pod's consent (`synap_space_hint`); a pod may ignore it. */
     spaceHint: string | null;
+    /**
+     * The `state` of a Synap Cloud return (the CP pod chooser answers
+     * `initiate_login_uri?iss=…&state=…`, or `?state=…&error=access_denied` when
+     * the person cancelled), shape-checked only. NOT verified here:
+     * send the request's query to the cloud handler (GET `paths.cloud`), which
+     * checks it against this browser's sealed cookie. Never act on `pod` because
+     * a state is present.
+     */
+    cloudState: string | null;
 }
 /**
- * Read a third-party-initiated login (OIDC Core §4, spec 17 §7.2): the browser
+ * Read a third-party-initiated login (OIDC Core §4): the browser
  * opens the app's `initiate_login_uri?iss=…&target_link_uri=…`. One parser for
- * the browser launch and, later, the Synap Cloud chooser's return.
+ * the browser launch and the Synap Cloud chooser's return (`cloudState`).
  */
 declare function acceptLaunch(url: string | URL, appOrigin: string, opts?: {
     allowInsecureLoopback?: boolean;
 }): LaunchHint;
 
+/** How long a Synap Cloud sign-in may take, from the click to the pod chooser's return. */
+declare const CLOUD_TRANSACTION_TTL_MS: number;
+/** A sealed `CloudTransaction`: opaque, safe to put in an HttpOnly cookie. */
+type SealedCloudTransaction = string & {
+    readonly __sealedCloudTransaction: true;
+};
+/** What a started Synap Cloud sign-in remembers (sealed; never sent to the CP). */
+interface CloudTransaction {
+    v: 1;
+    state: string;
+    clientId: string;
+    /** The CP base it was sent to. */
+    cloudUrl: string;
+    next: string | null;
+    spaceHint: string | null;
+    prompt: "consent" | null;
+    createdAt: number;
+}
+interface CloudConnectConfig {
+    /** The Control Plane's base URL, e.g. https://api.synap.live. Unset = no Synap Cloud option. */
+    cloudUrl?: string | null;
+    /** Accept a CP on http://localhost (development). */
+    allowInsecureLoopback?: boolean;
+}
+/** The CP base (no trailing slash), or a ConnectError (`misconfigured`). */
+declare function cloudBaseUrl(cloudUrl: string, opts?: {
+    allowInsecureLoopback?: boolean;
+}): string;
+/** Whether "Continue with Synap Cloud" can be offered: a valid Control Plane URL is configured. */
+declare function cloudConnectAvailable(config?: CloudConnectConfig | null): boolean;
+interface StartCloudConnectOptions extends CloudConnectConfig {
+    /** The app's client_id (its CIMD URL): the CP reads `initiate_login_uri` from it. */
+    clientId: string;
+    /**
+     * SERVER-ONLY app secret that seals the transaction. Required: without it the call throws `misconfigured`.
+     * Optional in the type only for 1.x semver; required in 2.0.
+     */
+    secret?: AppSecret;
+    /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
+    next?: string | null;
+    /** A space hint for the pod's consent (`synap_space_hint`); a pod may ignore it. */
+    spaceHint?: string | null;
+    /** Show the pod's consent again even if this browser is already connected to the pod the person picks. */
+    prompt?: "consent" | null;
+    /** @deprecated Ignored: the SDK always draws its own 32-byte state. Removed in 2.0. */
+    state?: string;
+    now?: () => number;
+}
+interface StartedCloudConnect {
+    /** Redirect the browser here (303): the CP's pod chooser. */
+    url: string;
+    /** Store in an HttpOnly cookie until the CP returns. */
+    transaction: SealedCloudTransaction;
+    /** ms since epoch. */
+    expiresAt: number;
+}
+/**
+ * Start a Synap Cloud sign-in. Throws `cp_unavailable` at once when no CP URL
+ * is configured, `misconfigured` without a secret: both SYNCHRONOUSLY, before
+ * a Promise exists, so wrap the call in try/catch rather than relying on
+ * `.catch` (kept from 1.3 for compatibility; 2.0 makes it a plain async
+ * function with a required secret).
+ */
+declare function startCloudConnect(opts: StartCloudConnectOptions): Promise<StartedCloudConnect>;
+interface AcceptCloudReturnOptions {
+    /** The URL the CP sent the browser back to (`?iss=…&state=…`). */
+    url: string | URL;
+    transaction: string | null | undefined;
+    clientId: string;
+    secret: AppSecret;
+    allowInsecureLoopback?: boolean;
+    now?: () => number;
+}
+interface CloudReturn {
+    /** The pod the person picked (canonical issuer), still to be discovered and validated. */
+    pod: string;
+    next: string | null;
+    spaceHint: string | null;
+    prompt: "consent" | null;
+}
+/**
+ * Check the CP's return against the sealed transaction of THIS browser.
+ * Throws `expired_transaction` (none, foreign, tampered or older than 10
+ * minutes), `mismatch` (the state is not this browser's, or no pod is named),
+ * `denied` (the person cancelled on the chooser: `error=access_denied`, no
+ * `iss`; nothing is started), `invalid_pod_address`.
+ * `state` is compared BEFORE anything else in the query is used.
+ */
+declare function acceptCloudReturn(opts: AcceptCloudReturnOptions): Promise<CloudReturn>;
+
+declare function isBrowserRuntime(): boolean;
+
 /** How long a started sign-in stays valid. */
 declare const TRANSACTION_TTL_MS: number;
-/** The refresh token's idle life when the pod does not say (spec 17 F5: 30 days). */
+/** The refresh token's idle life when the pod does not say (the pod's: 30 days). */
 declare const DEFAULT_REFRESH_IDLE_MS: number;
 /** A sealed `ConnectTransaction`: opaque, safe to put in an HttpOnly cookie. */
 type SealedTransaction = string & {
@@ -351,6 +918,12 @@ interface StartConnectOptions extends FlowOptions {
     spaceHint?: string | null;
     /** A same-origin path to land on afterwards (validate it first: `safeNextPath`). */
     next?: string | null;
+    /**
+     * `"consent"`: the person asked to see the consent screen again (to widen or
+     * narrow what the app may touch). Sent as OIDC `prompt=consent`; the sign-in
+     * is otherwise the same (fresh PKCE verifier and state).
+     */
+    prompt?: "consent" | null;
     allowInsecureLoopback?: boolean;
 }
 interface StartedConnect {
@@ -384,7 +957,9 @@ interface CallbackResult {
 declare function handleCallback(opts: HandleCallbackOptions): Promise<CallbackResult>;
 /**
  * A token response → a connection. On a refresh, `previous` supplies what the
- * response may omit (grant, user). A refresh response WITHOUT a new
+ * response may omit (grant, user, app; never `actsAs`). `expires_in` is read as sent: a refresh
+ * answered within the pod's reuse grace hands back the live key the
+ * first redeem got, with less than an hour left. A refresh response WITHOUT a new
  * refresh_token drops the old one: with single-use rotation, resending a
  * consumed token reads as theft and revokes the whole family.
  */
@@ -398,7 +973,7 @@ declare function parseTokenResponse(body: Record<string, unknown>, ctx: {
 }): PodConnection;
 /**
  * How long a rotation's result is remembered for its SPENT refresh token.
- * The pod (PB3) refuses a concurrent second redeem softly, but a token
+ * The pod refuses a concurrent second redeem softly, but a token
  * presented AGAIN after its use is a reuse: the whole family and the live
  * access key are revoked. A browser easily sends that replay: parallel
  * requests, a second tab, a response it had not stored yet, all still
@@ -408,7 +983,7 @@ declare function parseTokenResponse(body: Record<string, unknown>, ctx: {
 declare const ROTATION_MEMORY_MS: number;
 /**
  * Exchange the refresh token for a new access token and the rotated refresh
- * token (PB3: single-use, 30 days from issue, reach re-derived by the pod).
+ * token (single-use, 30 days from issue, its reach re-derived by the pod).
  *
  * SINGLE-FLIGHT per connection within this process: concurrent callers share
  * one request, and for `ROTATION_MEMORY_MS` after it a caller still holding
@@ -422,7 +997,7 @@ declare const ROTATION_MEMORY_MS: number;
  * (invalid_grant while it should live: spent, revoked, the app removed or
  * narrowed to nothing, or a concurrent redeem lost), `misconfigured`
  * (invalid_client, unauthorized_client), `rate_limited`, `pod_unreachable`,
- * `server_error`.
+ * `pod_moved` (the token endpoint answered a redirect), `server_error`.
  */
 declare function refreshConnection(connection: PodConnection, opts?: FlowOptions): Promise<PodConnection>;
 /**
@@ -437,6 +1012,4 @@ declare function revokeConnection(connection: PodConnection, opts?: FlowOptions)
 /** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */
 declare function pkceChallenge(verifier: string): Promise<string>;
 
-declare function isBrowserRuntime(): boolean;
-
-export { AppRequest, type AppSecret, CONNECT_ERROR_CODES, type CallbackResult, ClientMetadataDocument, ConnectError, type ConnectErrorCode, type ConnectTransaction, type ConnectionStore, type CookieNames, DEFAULT_PATHS, DEFAULT_REFRESH_IDLE_MS, type DiscoverOptions, type FlowOptions, type HandleCallbackOptions, type LaunchHint, MIN_SECRET_LENGTH, type Opened, type PodAppAuth, type PodAppAuthConfig, type PodAppPaths, type PodClient, type PodClientOptions, PodConnection, type PodError, type PodErrorCode, PodGrant, PodIssuer, type PodResult, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOutcome, type RefreshStatus, type SealPurpose, type SealedCookieStoreOptions, type SealedTransaction, type StartConnectOptions, type StartedConnect, TRANSACTION_TTL_MS, acceptLaunch, applySetCookies, buildClientMetadata, can, canonicalPodUrl, cloudConnectAvailable, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, isBrowserRuntime, isConnectError, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, startCloudConnect, startConnect, unseal };
+export { type AcceptCloudReturnOptions, AppRequest, type AppSecret, type ApproveProposalOptions, CLOUD_TRANSACTION_TTL_MS, CONNECT_ERROR_CODES, type CallbackResult, ClientMetadataDocument, type CloudConnectConfig, type CloudReturn, type CloudTransaction, ConnectError, type ConnectErrorCode, type ConnectTransaction, type ConnectionStore, type CookieNames, DEFAULT_PATHS, DEFAULT_REFRESH_IDLE_MS, type DiscoverOptions, type FlowOptions, type GetDocumentOptions, type GetEntityConnectionsOptions, type HandleCallbackOptions, type LaunchHint, type ListEntitiesOptions, type ListFocusSessionsOptions, type ListPendingProposalsOptions, MARKER_TTL_SEC, MIN_SECRET_LENGTH, type Opened, type PendingProposal, type PendingProposals, PodActsAs, type PodAppAuth, type PodAppAuthConfig, type PodAppClientOptions, type PodAppPaths, type PodApproval, type PodClient, type PodClientOptions, PodConnection, type PodConnectionSource, type PodDocument, type PodDocumentSection, type PodEntity, type PodEntityConnection, type PodEntityConnections, type PodError, type PodErrorCode, type PodFileUrl, type PodFocusSession, PodGrant, PodIssuer, type PodRefusalReason, type PodResult, type PodSessionSlot, type PodSessionStatus, PodSpace, type PodWriteResult, type QueryValue, REFRESH_WINDOW_MS, ROTATION_MEMORY_MS, type RefreshOptions, type RefreshOutcome, type RefreshStatus, type SealPurpose, type SealedCloudTransaction, type SealedCookieStoreOptions, type SealedTransaction, type StartCloudConnectOptions, type StartConnectOptions, type StartedCloudConnect, type StartedConnect, TRANSACTION_TTL_MS, acceptCloudReturn, acceptLaunch, applySetCookies, buildClientMetadata, can, canonicalPodUrl, cloudBaseUrl, cloudConnectAvailable, connectionActsAs, connectionExpiresAt, cookieNames, createPodAppAuth, createPodClient, createSealedCookieStore, discoverPod, handleCallback, humanSlots, isBrowserRuntime, isConnectError, isPrefetchOrAsset, markerCookie, openTransaction, parseConnectErrorCode, parseTokenResponse, pkceChallenge, readMarker, refreshConnection, reviewUrlFor, revokeConnection, safeNextPath, seal, spaces, startCloudConnect, startConnect, unseal };