@book.dev/sdk 3.10.0 → 3.14.0

package/dist/types.d.ts

@@ -47,12 +47,199 @@ export interface PageSnapshot {
      */
     authors?: Array<[string, string]>;
 }
+/**
+ * Monotonic optimistic-concurrency token for one durable entity. Implementing
+ * servers return positive safe integers; see `docs/write-contract.md`.
+ */
+export type EntityRev = number;
+/** A representation that is guaranteed to carry its concurrency token. */
+export type WithRev<Shape> = Shape & {
+    rev: EntityRev;
+};
+/** Additive CAS input shared by revision-aware write payloads. Omission is LWW. */
+export interface ExpectedRevInput {
+    expectedRev?: EntityRev;
+}
+/** Opaque lexicographically ordered fractional key used by the CWD-12 target contract. */
+export type StablePosition = string;
+/** Stable page-id → position mapping; unlike `orderedIds`, identity survives insertion. */
+export type PagePositionRecord = Readonly<Record<string, StablePosition>>;
+/** Additive move input spanning wave 1 and the post-CWD-12 position contract. */
+export interface PageMoveInput extends ExpectedRevInput {
+    parentId: string | null;
+    /** Post-CWD-12 input; exactly the route page id is normally the sole key. */
+    positions?: PagePositionRecord;
+    /** @deprecated Wave-1 LWW sibling order; use {@link positions} after CWD-12. */
+    orderedIds?: string[];
+}
+/** Target input for position-record row ordering after the CWD-12 migration. */
+export interface PageOrderInput {
+    positions: PagePositionRecord;
+}
+/** UUID v4/v7 value carried in the `Idempotency-Key` request header. */
+export type IdempotencyKey = string;
+/** Request metadata accepted by the SDK write chokepoint (not part of JSON bodies). */
+export interface WriteRequestOptions {
+    idempotencyKey?: IdempotencyKey;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** The durable entity whose guarded write conflicted. */
+export type WriteEntityRef = {
+    kind: 'page';
+    id: string;
+} | {
+    kind: 'database-row';
+    id: string;
+    databaseId: string;
+} | {
+    kind: 'database';
+    id: string;
+} | {
+    kind: 'instance-config';
+    id: 'instance';
+};
+/** Stable server codes introduced for the durable-write contract. */
+export type WriteServerErrorCode = 'rev-conflict' | 'idempotency-key-reused' | 'invalid-input' | 'unauthorized' | 'forbidden' | 'not-found' | 'rate-limited' | 'server-error';
+/** Minimum non-2xx JSON body returned by durable write routes. */
+export interface WriteErrorEnvelope<Code extends string = WriteServerErrorCode> {
+    readonly error: string;
+    readonly code: Code;
+    readonly retryable: boolean;
+}
+/** Optional field-level detail on an {@link WriteValidationEnvelope}. */
+export interface WriteValidationIssue {
+    readonly path?: string;
+    readonly code?: string;
+    readonly message: string;
+}
+/** Structured invalid-input response; `issues` is omitted for request-wide errors. */
+export interface WriteValidationEnvelope extends WriteErrorEnvelope<'invalid-input'> {
+    readonly retryable: false;
+    readonly issues?: WriteValidationIssue[];
+}
+/** A key was previously committed for a different request fingerprint. */
+export interface WriteIdempotencyKeyReuseEnvelope extends WriteErrorEnvelope<'idempotency-key-reused'> {
+    readonly retryable: false;
+}
+/** Links offered by wave-1 conflict resolution. */
+export interface WriteConflictLinks {
+    /** Permission-appropriate GET endpoint used when `current` is omitted. */
+    readonly self: string;
+    /** Page/row history endpoint; `null` for entities without version history. */
+    readonly versionHistory: string | null;
+}
+/**
+ * Fields shared by every HTTP 409 CAS response. `current` is specialized by the
+ * responding route's projection in the discriminated members below.
+ */
+interface WriteConflictBase extends WriteErrorEnvelope<'rev-conflict'> {
+    readonly retryable: false;
+    readonly expectedRev: EntityRev;
+    readonly currentRev: EntityRev;
+    readonly links: WriteConflictLinks;
+}
+/** CAS response from a page route, secondarily discriminated by route projection. */
+export type PageConflict = (WriteConflictBase & {
+    readonly entity: Extract<WriteEntityRef, {
+        kind: 'page';
+    }>;
+    readonly projection: 'page';
+    readonly current: WithRev<StoredPage> | null;
+}) | (WriteConflictBase & {
+    readonly entity: Extract<WriteEntityRef, {
+        kind: 'page';
+    }>;
+    readonly projection: 'visibility';
+    readonly current: WithRev<PageVisibilitySettings> | null;
+}) | (WriteConflictBase & {
+    readonly entity: Extract<WriteEntityRef, {
+        kind: 'page';
+    }>;
+    readonly projection: 'agent-edits';
+    readonly current: WithRev<AgentEditsPolicySettings> | null;
+});
+/** CAS response from a database-row property route. */
+export interface DatabaseRowConflict extends WriteConflictBase {
+    readonly entity: Extract<WriteEntityRef, {
+        kind: 'database-row';
+    }>;
+    readonly current: WithRev<import('./database').DatabaseRow> | null;
+}
+/** CAS response from a database route. */
+export interface DatabaseConflict extends WriteConflictBase {
+    readonly entity: Extract<WriteEntityRef, {
+        kind: 'database';
+    }>;
+    readonly current: WithRev<import('./database').StoredDatabase> | null;
+}
+/** CAS response from the instance-policy route. */
+export interface InstanceConfigConflict extends WriteConflictBase {
+    readonly entity: Extract<WriteEntityRef, {
+        kind: 'instance-config';
+    }>;
+    readonly current: WithRev<import('./provenance').InstanceConfig> | null;
+}
+/** HTTP 409 body for an opt-in CAS miss, discriminated by `entity.kind`. */
+export type WriteConflictEnvelope = PageConflict | DatabaseRowConflict | DatabaseConflict | InstanceConfigConflict;
+/** Stable discriminators used by the SDK's future runtime `WriteError` classes. */
+export type WriteErrorKind = 'timeout' | 'abort' | 'conflict' | 'idempotency-reuse' | 'validation' | 'authorization' | 'rate-limit' | 'transport' | 'server' | 'http';
+/** Shared structural contract implemented by every SDK `WriteError` class. */
+export interface WriteErrorInfo<Kind extends WriteErrorKind = WriteErrorKind, Status extends number | null = number | null, Details = unknown> {
+    readonly kind: Kind;
+    readonly status: Status;
+    readonly retryable: boolean;
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Details;
+}
+export interface WriteTimeoutErrorInfo extends WriteErrorInfo<'timeout', null | 408 | 504> {
+    readonly retryable: true;
+}
+export interface WriteAbortErrorInfo extends WriteErrorInfo<'abort', null> {
+    readonly retryable: false;
+}
+export interface WriteConflictErrorInfo extends WriteErrorInfo<'conflict', 409, WriteConflictEnvelope> {
+    readonly retryable: false;
+    readonly code: 'rev-conflict';
+}
+export interface WriteIdempotencyReuseErrorInfo extends WriteErrorInfo<'idempotency-reuse', 409, WriteIdempotencyKeyReuseEnvelope> {
+    readonly retryable: false;
+    readonly code: 'idempotency-key-reused';
+}
+export interface WriteValidationErrorInfo extends WriteErrorInfo<'validation', 400 | 413 | 422, WriteValidationEnvelope> {
+    readonly retryable: false;
+}
+export interface WriteAuthorizationErrorInfo extends WriteErrorInfo<'authorization', 401 | 403> {
+    readonly retryable: false;
+}
+export interface WriteRateLimitErrorInfo extends WriteErrorInfo<'rate-limit', 429> {
+    readonly retryable: true;
+    /** Milliseconds parsed from an HTTP `Retry-After` seconds value, when present. */
+    readonly retryAfterMs?: number;
+}
+export interface WriteTransportErrorInfo extends WriteErrorInfo<'transport', null> {
+    readonly retryable: true;
+}
+export interface WriteServerErrorInfo extends WriteErrorInfo<'server', 500 | 502 | 503> {
+    readonly retryable: true;
+}
+export interface WriteHttpErrorInfo extends WriteErrorInfo<'http', number> {
+    readonly retryable: false;
+}
+/** Exhaustive structural taxonomy implemented by the SDK error classes. */
+export type WriteErrorContract = WriteTimeoutErrorInfo | WriteAbortErrorInfo | WriteConflictErrorInfo | WriteIdempotencyReuseErrorInfo | WriteValidationErrorInfo | WriteAuthorizationErrorInfo | WriteRateLimitErrorInfo | WriteTransportErrorInfo | WriteServerErrorInfo | WriteHttpErrorInfo;
 /** An empty snapshot, for initializing a brand-new page. */
 export declare const emptyPageSnapshot: () => PageSnapshot;
 /** Lightweight page record for listings (no `data` payload). */
 export interface PageMeta {
     id: string;
+    /** Optimistic-concurrency token; absent only when reading from a legacy server. */
+    rev?: EntityRev;
     name: string | null;
+    /** Whether the page participates in discovery surfaces. Independent of who
+     *  may read it; omitted by older servers. */
+    listed?: boolean;
     /** The page's emoji icon, or `null` when none is set — projected from
      *  `page.properties` so lists (sidebar, tabs, mentions) resolve it directly,
      *  without a per-page fetch. */
@@ -106,6 +293,8 @@ export interface PageGraph {
 /** A full page as returned by the store. `data` is the document snapshot. */
 export interface StoredPage {
     id: string;
+    /** Optimistic-concurrency token; absent only when reading from a legacy server. */
+    rev?: EntityRev;
     name: string | null;
     data: PageSnapshot;
     /** The database this page *hosts*, if any (mirrors {@link PageMeta.hostedDatabaseId}). */
@@ -160,10 +349,12 @@ export interface StoredPageVersion extends PageVersionMeta {
  * not set through this payload — they are managed by the database row APIs so a
  * routine content save never clobbers them.
  */
-export interface PageInput {
+export interface PageInput extends ExpectedRevInput {
     id?: string;
     name?: string | null;
     data: PageSnapshot;
+    /** Initial discovery posture for a new page. Independent of visibility. */
+    listed?: boolean;
     /**
      * The page to nest this new page under. Applied only when the page is first
      * created; a later content save with the same id leaves the parent untouched.
@@ -199,6 +390,22 @@ export type Visibility = PageVisibility;
 /** Every {@link PageVisibility} value, in escalating-privacy order — the source of
  *  truth for server-side validation and the share dialog's scope picker. */
 export declare const PAGE_VISIBILITIES: readonly PageVisibility[];
+/** The state returned by the co-located page visibility/listing endpoint.
+ * `listed` is a discovery flag, not another rung in {@link PageVisibility}. */
+export interface PageVisibilitySettings {
+    /** The owning page's concurrency token; absent only on a legacy server. */
+    rev?: EntityRev;
+    visibility: PageVisibility;
+    listed: boolean;
+}
+/** A non-empty update accepted by the page visibility/listing endpoint. */
+export type PageVisibilityUpdate = ({
+    visibility: PageVisibility;
+    listed?: boolean;
+} | {
+    visibility?: PageVisibility;
+    listed: boolean;
+}) & ExpectedRevInput;
 /**
  * The two INSTANCE-level agent-edits modes (AGED-1). Governs whether an agent (an
  * MCP tool or the built-in AI) writes a page DIRECTLY or persists its change as a
@@ -213,6 +420,17 @@ export type AgentEditsMode = 'suggest' | 'direct';
  * Resolve to an effective {@link AgentEditsMode} with {@link resolveAgentEdits}.
  */
 export type AgentEditsPolicy = 'inherit' | 'suggest' | 'direct';
+/** Revision-bearing response from a page's agent-edits policy endpoint. */
+export interface AgentEditsPolicySettings {
+    /** The owning page's concurrency token; absent only on a legacy server. */
+    rev?: EntityRev;
+    agentEdits: AgentEditsPolicy;
+    effective: AgentEditsMode;
+}
+/** Revision-aware input for a page's agent-edits policy endpoint. */
+export interface AgentEditsPolicyUpdate extends ExpectedRevInput {
+    agentEdits: AgentEditsPolicy;
+}
 /** Every {@link AgentEditsMode} — the source of truth for validating an instance
  *  policy write (`PUT /api/instance`). */
 export declare const AGENT_EDITS_MODES: readonly AgentEditsMode[];
@@ -363,3 +581,4 @@ export interface ServerControls {
      * Absent on the web / an old host that predates the capability. */
     setAgentLocalTcp?(enabled: boolean): Promise<ServerInfo>;
 }
+export {};

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0CH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAiB,EAAE,CAAC,CAAC;IACpD,QAAQ,EAAE,EAAC,MAAM,EAAE,EAAE,EAAC;IACtB,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,EAAE;CACV,CAAC,CAAC;AAgKH;4EAC4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAA8B;IAC1D,SAAS;IACT,QAAQ;IACR,eAAe;IACf,SAAS;IACT,YAAY;CACb,CAAC;AAkBF;0CAC0C;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAA8B,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAElF;gDACgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAgC,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAElG;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAsB,EACtB,QAAoC;IAEpC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,QAAQ,IAAI,SAAS,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsRH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAiB,EAAE,CAAC,CAAC;IACpD,QAAQ,EAAE,EAAC,MAAM,EAAE,EAAE,EAAC;IACtB,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,EAAE;CACV,CAAC,CAAC;AAyKH;4EAC4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAA8B;IAC1D,SAAS;IACT,QAAQ;IACR,eAAe;IACf,SAAS;IACT,YAAY;CACb,CAAC;AA8CF;0CAC0C;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAA8B,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAElF;gDACgD;AAChD,MAAM,CAAC,MAAM,oBAAoB,GAAgC,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAElG;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAsB,EACtB,QAAoC;IAEpC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,QAAQ,IAAI,SAAS,CAAC;AAC/B,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@book.dev/sdk",
-  "version": "3.10.0",
+  "version": "3.14.0",
   "description": "Shared OpenBook types and HTTP client used by the server, desktop, and web.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/eliotlim/OpenBook.git",
+    "url": "git+https://github.com/lab255/OpenBook.git",
     "directory": "packages/sdk"
   },
   "publishConfig": {