@relayfile/core 0.7.12 → 0.7.14

package/dist/storage.d.ts

@@ -105,6 +105,11 @@ export interface StorageAdapter {
     nextEventId(): string;
     enqueueWriteback(item: WritebackItem): void;
     getPendingWritebacks(): WritebackItem[];
+    /**
+     * Optional: return the schema identifier the daemon validates this
+     * writeback resource against. Return null if no schema is registered.
+     */
+    getWritebackSchemaId?(provider: string, resource: string): string | null;
     getEnvelopeByDelivery?(workspaceId: string, provider: string, deliveryId: string): EnvelopeRow | null;
     putEnvelope?(envelope: EnvelopeRow): void;
     putEnvelopeDeliveryAlias?(workspaceId: string, provider: string, deliveryId: string, envelopeId: string): void;

package/dist/writeback.d.ts

@@ -7,14 +7,50 @@
  *   - dead-letter handling
  *   - retry logic
  */
-import type { StorageAdapter, WritebackItem } from "./storage.js";
+import type { Paginated, StorageAdapter, WritebackItem } from "./storage.js";
 export declare const MAX_WRITEBACK_ATTEMPTS = 3;
 export declare const WRITEBACK_RETRY_DELAY_MS = 30000;
+export type WritebackListState = "pending" | "succeeded" | "failed" | "dead_lettered";
+export interface WritebackListItem extends WritebackItem {
+    state: WritebackListState;
+    attemptCount: number;
+    lastError: string | null;
+    nextAttemptAt: string | null;
+    /** Provider slug, copied from OperationRow.provider. */
+    provider: string;
+}
+export interface ListWritebacksOptions {
+    state: WritebackListState;
+    cursor?: string;
+    limit?: number;
+}
+export type DeadLetterErrorCode = "schema_violation" | "provider_4xx" | "provider_5xx_exhausted" | "timeout";
+export interface DeadLetterError {
+    code: DeadLetterErrorCode;
+    message: string;
+    providerStatus?: number;
+    providerResponse?: Record<string, unknown> | unknown[];
+    attempts: number;
+    firstAttemptAt: string;
+    lastAttemptAt: string;
+    opId: string;
+}
+export interface WritebackResourceSchemaRef {
+    /** Provider slug, e.g. "linear". */
+    provider: string;
+    /** Resource slug, e.g. "comments". */
+    resource: string;
+    /** Identifier the daemon uses to load the schema. */
+    schemaId: string;
+}
 export interface DispatchWritebackCallbacks {
     send(item: WritebackItem): void;
     onRetryScheduled?(item: WritebackItem, nextAttemptAt: string): void;
     now?(): string;
 }
+export declare function listWritebacks(storage: StorageAdapter, options: ListWritebacksOptions): Paginated<WritebackListItem>;
+export declare function normalizeDeadLetterError(input: unknown): DeadLetterError;
+export declare function resolveWritebackSchemaRef(storage: StorageAdapter, writebackPath: string): WritebackResourceSchemaRef | null;
 export declare function getPendingWritebacks(storage: StorageAdapter): WritebackItem[];
 export declare function acknowledgeWriteback(storage: StorageAdapter, itemId: string, success: boolean, errorMsg?: string, correlationId?: string, now?: () => string): {
     status: string;

package/dist/writeback.deadletter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/writeback.deadletter.test.js

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { normalizeDeadLetterError, } from "./writeback.js";
+describe("normalizeDeadLetterError", () => {
+    it("round-trips a canonical dead-letter error", () => {
+        const input = {
+            code: "schema_violation",
+            message: "body must include event",
+            providerStatus: 422,
+            providerResponse: { error: "missing event" },
+            attempts: 4,
+            firstAttemptAt: "2026-05-13T10:00:00.000Z",
+            lastAttemptAt: "2026-05-13T10:05:00.000Z",
+            opId: "op_dead",
+        };
+        const normalized = normalizeDeadLetterError(input);
+        expect(normalized).toEqual(input);
+        expect(Object.isFrozen(normalized)).toBe(true);
+    });
+    it("rejects unknown code values", () => {
+        expect(() => normalizeDeadLetterError({
+            ...canonicalInput(),
+            code: "provider_unknown",
+        })).toThrow(TypeError);
+    });
+    it("trims message whitespace", () => {
+        expect(normalizeDeadLetterError({
+            ...canonicalInput(),
+            message: "  timed out  ",
+        }).message).toBe("timed out");
+    });
+    it("rejects missing required fields", () => {
+        for (const field of ["firstAttemptAt", "lastAttemptAt", "opId"]) {
+            const input = canonicalInput();
+            delete input[field];
+            expect(() => normalizeDeadLetterError(input)).toThrow(TypeError);
+        }
+    });
+    it("accepts optional provider status and object response", () => {
+        expect(normalizeDeadLetterError({
+            ...canonicalInput(),
+            providerStatus: 504,
+            providerResponse: { retryable: true },
+        })).toMatchObject({
+            providerStatus: 504,
+            providerResponse: { retryable: true },
+        });
+    });
+    it("accepts array provider responses matching the canonical schema", () => {
+        expect(normalizeDeadLetterError({
+            ...canonicalInput(),
+            providerResponse: [{ error: "bad request" }],
+        }).providerResponse).toEqual([{ error: "bad request" }]);
+    });
+});
+function canonicalInput() {
+    return {
+        code: "provider_5xx_exhausted",
+        message: "upstream failed",
+        attempts: 3,
+        firstAttemptAt: "2026-05-13T10:00:00.000Z",
+        lastAttemptAt: "2026-05-13T10:05:00.000Z",
+        opId: "op_123",
+    };
+}

package/dist/writeback.js

@@ -10,6 +10,78 @@
 import { createEvent } from "./events.js";
 export const MAX_WRITEBACK_ATTEMPTS = 3;
 export const WRITEBACK_RETRY_DELAY_MS = 30_000;
+export function listWritebacks(storage, options) {
+    const state = normalizeWritebackListState(options.state);
+    const limit = clampLimit(options.limit);
+    const sortedItems = listAllOperationsForState(storage, state)
+        .filter((op) => op.status === state)
+        .map((op) => toWritebackListItem(storage, op, state))
+        .sort(compareWritebackListItems);
+    let start = 0;
+    if (options.cursor) {
+        const cursorIndex = sortedItems.findIndex((item) => item.id === options.cursor);
+        if (cursorIndex < 0) {
+            return { items: [], nextCursor: null };
+        }
+        start = cursorIndex + 1;
+    }
+    const items = sortedItems.slice(start, start + limit);
+    return {
+        items,
+        nextCursor: start + limit < sortedItems.length
+            ? (items[items.length - 1]?.id ?? null)
+            : null,
+    };
+}
+export function normalizeDeadLetterError(input) {
+    if (!isRecord(input)) {
+        throw new TypeError("dead-letter error must be an object");
+    }
+    const code = normalizeDeadLetterErrorCode(input.code);
+    const message = requiredString(input.message, "message").trim();
+    const attempts = requiredPositiveInteger(input.attempts, "attempts");
+    const firstAttemptAt = requiredIsoTimestamp(input.firstAttemptAt, "firstAttemptAt");
+    const lastAttemptAt = requiredIsoTimestamp(input.lastAttemptAt, "lastAttemptAt");
+    const opId = requiredString(input.opId, "opId").trim();
+    if (!message) {
+        throw new TypeError("dead-letter error message is required");
+    }
+    if (!opId) {
+        throw new TypeError("dead-letter error opId is required");
+    }
+    const normalized = {
+        code,
+        message,
+        attempts,
+        firstAttemptAt,
+        lastAttemptAt,
+        opId,
+    };
+    if (input.providerStatus !== undefined) {
+        normalized.providerStatus = optionalProviderStatus(input.providerStatus);
+    }
+    if (input.providerResponse !== undefined) {
+        normalized.providerResponse = optionalProviderResponse(input.providerResponse);
+    }
+    // Keep this shape aligned with relayfile/schemas/relay/dead-letter-error.schema.json.
+    return Object.freeze(normalized);
+}
+export function resolveWritebackSchemaRef(storage, writebackPath) {
+    const parsed = parseWritebackPath(writebackPath);
+    if (!parsed) {
+        return null;
+    }
+    const registeredSchemaId = storage.getWritebackSchemaId?.(parsed.provider, parsed.resource);
+    if (registeredSchemaId === null) {
+        return null;
+    }
+    return {
+        provider: parsed.provider,
+        resource: parsed.resource,
+        schemaId: registeredSchemaId?.trim() ||
+            `${parsed.provider}/${parsed.resource}.schema.json`,
+    };
+}
 export function getPendingWritebacks(storage) {
     const items = [];
     let cursor;
@@ -124,6 +196,36 @@ function normalizePath(path) {
     const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
     return prefixed.length > 1 ? prefixed.replace(/\/+$/, "") : "/";
 }
+function normalizeWritebackListState(state) {
+    if (state === "pending" ||
+        state === "succeeded" ||
+        state === "failed" ||
+        state === "dead_lettered") {
+        return state;
+    }
+    throw new TypeError("writeback state must be pending, succeeded, failed, or dead_lettered");
+}
+function clampLimit(limit) {
+    return Math.max(1, Math.min(limit ?? 100, 1000));
+}
+function listAllOperationsForState(storage, state) {
+    const operations = [];
+    let cursor;
+    do {
+        const page = storage.listOperations({
+            status: state,
+            cursor,
+            limit: 1000,
+        });
+        operations.push(...page.items);
+        const nextCursor = page.nextCursor ?? undefined;
+        if (!nextCursor || nextCursor === cursor) {
+            break;
+        }
+        cursor = nextCursor;
+    } while (cursor);
+    return operations;
+}
 function normalizeError(errorMsg) {
     return errorMsg?.trim() || "provider reported failure";
 }
@@ -146,3 +248,90 @@ function toWritebackItem(storage, item) {
         correlationId: item.correlationId,
     };
 }
+function toWritebackListItem(storage, op, state) {
+    return {
+        id: op.opId,
+        workspaceId: storage.getWorkspaceId(),
+        path: normalizePath(op.path),
+        revision: op.revision,
+        correlationId: op.correlationId || "",
+        state,
+        attemptCount: op.attemptCount,
+        lastError: op.lastError,
+        nextAttemptAt: op.nextAttemptAt,
+        provider: op.provider,
+    };
+}
+function compareWritebackListItems(left, right) {
+    if (left.nextAttemptAt && right.nextAttemptAt) {
+        const byNextAttempt = left.nextAttemptAt.localeCompare(right.nextAttemptAt);
+        if (byNextAttempt !== 0) {
+            return byNextAttempt;
+        }
+    }
+    else if (left.nextAttemptAt) {
+        return -1;
+    }
+    else if (right.nextAttemptAt) {
+        return 1;
+    }
+    return left.id.localeCompare(right.id);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeDeadLetterErrorCode(value) {
+    if (value === "schema_violation" ||
+        value === "provider_4xx" ||
+        value === "provider_5xx_exhausted" ||
+        value === "timeout") {
+        return value;
+    }
+    throw new TypeError("dead-letter error code is invalid");
+}
+function requiredString(value, field) {
+    if (typeof value !== "string") {
+        throw new TypeError(`dead-letter error ${field} must be a string`);
+    }
+    return value;
+}
+function requiredPositiveInteger(value, field) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new TypeError(`dead-letter error ${field} must be a positive integer`);
+    }
+    return value;
+}
+function requiredIsoTimestamp(value, field) {
+    const timestamp = requiredString(value, field).trim();
+    if (!timestamp || Number.isNaN(Date.parse(timestamp))) {
+        throw new TypeError(`dead-letter error ${field} must be an ISO timestamp`);
+    }
+    return timestamp;
+}
+function optionalProviderStatus(value) {
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 100 ||
+        value > 599) {
+        throw new TypeError("dead-letter error providerStatus must be an HTTP status");
+    }
+    return value;
+}
+function optionalProviderResponse(value) {
+    if (!isRecord(value) && !Array.isArray(value)) {
+        throw new TypeError("dead-letter error providerResponse must be an object or array");
+    }
+    return value;
+}
+function parseWritebackPath(writebackPath) {
+    const parts = normalizePath(writebackPath).split("/").filter(Boolean);
+    if (parts.length < 3) {
+        return null;
+    }
+    const provider = parts[0]?.trim().toLowerCase();
+    const resource = parts[parts.length - 2]?.trim().toLowerCase();
+    if (!provider || !resource || resource.startsWith(".")) {
+        return null;
+    }
+    return { provider, resource };
+}

package/dist/writeback.list.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/writeback.list.test.js

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import { MAX_WRITEBACK_ATTEMPTS, listWritebacks, } from "./writeback.js";
+describe("listWritebacks", () => {
+    it("lists pending writebacks deterministically by nextAttemptAt with nulls last", () => {
+        const storage = makeStorage([
+            operation({
+                opId: "op_null",
+                path: "/linear/comments/null.json",
+                nextAttemptAt: null,
+            }),
+            operation({
+                opId: "op_late",
+                path: "/linear/comments/late.json",
+                nextAttemptAt: "2026-05-13T12:00:00.000Z",
+            }),
+            operation({
+                opId: "op_early",
+                path: "/linear/comments/early.json",
+                nextAttemptAt: "2026-05-13T11:00:00.000Z",
+            }),
+        ]);
+        const first = listWritebacks(storage, { state: "pending" }).items;
+        const second = listWritebacks(storage, { state: "pending" }).items;
+        expect(first.map((item) => item.id)).toEqual([
+            "op_early",
+            "op_late",
+            "op_null",
+        ]);
+        expect(second).toEqual(first);
+        expect(first[0]).toMatchObject({
+            workspaceId: "ws_core",
+            path: "/linear/comments/early.json",
+            state: "pending",
+            attemptCount: 0,
+            provider: "linear",
+        });
+    });
+    it("sorts before applying the requested page limit", () => {
+        const storage = makeStorage([
+            operation({
+                opId: "op_late",
+                nextAttemptAt: "2026-05-13T12:00:00.000Z",
+            }),
+            operation({
+                opId: "op_null",
+                nextAttemptAt: null,
+            }),
+            operation({
+                opId: "op_early",
+                nextAttemptAt: "2026-05-13T10:00:00.000Z",
+            }),
+        ], { sort: false });
+        const first = listWritebacks(storage, { state: "pending", limit: 1 });
+        const second = listWritebacks(storage, {
+            state: "pending",
+            cursor: first.nextCursor ?? undefined,
+            limit: 1,
+        });
+        expect(first.items.map((item) => item.id)).toEqual(["op_early"]);
+        expect(first.nextCursor).toBe("op_early");
+        expect(second.items.map((item) => item.id)).toEqual(["op_late"]);
+        expect(second.nextCursor).toBe("op_late");
+    });
+    it("lists dead-lettered writebacks with retry metadata", () => {
+        const storage = makeStorage([
+            operation({
+                opId: "op_dead",
+                status: "dead_lettered",
+                attemptCount: MAX_WRITEBACK_ATTEMPTS,
+                lastError: "schema validation failed",
+            }),
+            operation({ opId: "op_pending", status: "pending" }),
+        ]);
+        expect(listWritebacks(storage, { state: "dead_lettered" }).items).toEqual([
+            expect.objectContaining({
+                id: "op_dead",
+                state: "dead_lettered",
+                attemptCount: MAX_WRITEBACK_ATTEMPTS,
+                lastError: "schema validation failed",
+            }),
+        ]);
+    });
+    it("lists succeeded and failed writebacks separately", () => {
+        const storage = makeStorage([
+            operation({ opId: "op_succeeded", status: "succeeded" }),
+            operation({ opId: "op_failed", status: "failed", lastError: "timeout" }),
+            operation({ opId: "op_pending", status: "pending" }),
+        ]);
+        expect(listWritebacks(storage, { state: "succeeded" }).items).toEqual([
+            expect.objectContaining({ id: "op_succeeded", state: "succeeded" }),
+        ]);
+        expect(listWritebacks(storage, { state: "failed" }).items).toEqual([
+            expect.objectContaining({
+                id: "op_failed",
+                state: "failed",
+                lastError: "timeout",
+            }),
+        ]);
+    });
+    it("rejects unknown states", () => {
+        const storage = makeStorage([]);
+        expect(() => listWritebacks(storage, { state: "dead" })).toThrow(TypeError);
+    });
+    it("paginates using the returned operation cursor", () => {
+        const storage = makeStorage([
+            operation({ opId: "op_1", nextAttemptAt: "2026-05-13T10:00:00.000Z" }),
+            operation({ opId: "op_2", nextAttemptAt: "2026-05-13T11:00:00.000Z" }),
+            operation({ opId: "op_3", nextAttemptAt: "2026-05-13T12:00:00.000Z" }),
+            operation({ opId: "op_4", nextAttemptAt: "2026-05-13T13:00:00.000Z" }),
+            operation({ opId: "op_5", nextAttemptAt: "2026-05-13T14:00:00.000Z" }),
+        ]);
+        const first = listWritebacks(storage, { state: "pending", limit: 2 });
+        const second = listWritebacks(storage, {
+            state: "pending",
+            cursor: first.nextCursor ?? undefined,
+            limit: 2,
+        });
+        expect(first.items.map((item) => item.id)).toEqual(["op_1", "op_2"]);
+        expect(first.nextCursor).toBe("op_2");
+        expect(second.items.map((item) => item.id)).toEqual(["op_3", "op_4"]);
+        expect(second.nextCursor).toBe("op_4");
+    });
+    it("returns an empty page for unknown cursors", () => {
+        const storage = makeStorage([operation({ opId: "op_1" })]);
+        expect(listWritebacks(storage, {
+            state: "pending",
+            cursor: "op_missing",
+        })).toEqual({ items: [], nextCursor: null });
+    });
+});
+function operation(overrides) {
+    return {
+        opId: "op_default",
+        path: "/linear/issues/AGE-16__abc/comments/wb.json",
+        revision: "rev_1",
+        action: "file_upsert",
+        provider: "linear",
+        status: "pending",
+        attemptCount: 0,
+        lastError: null,
+        nextAttemptAt: null,
+        correlationId: "corr_1",
+        ...overrides,
+    };
+}
+function makeStorage(operations, options = {}) {
+    const sortedOperations = options.sort === false ? [...operations] : [...operations].sort(compareOperations);
+    return {
+        getFile: () => null,
+        listFiles: () => [],
+        putFile: () => undefined,
+        deleteFile: () => undefined,
+        appendEvent: () => undefined,
+        listEvents: () => ({ items: [], nextCursor: null }),
+        getRecentEvents: () => [],
+        getOperation: (opId) => sortedOperations.find((operationRow) => operationRow.opId === opId) ??
+            null,
+        putOperation: () => undefined,
+        listOperations: (options) => {
+            const matching = sortedOperations.filter((op) => {
+                return !options.status || op.status === options.status;
+            });
+            const start = options.cursor
+                ? matching.findIndex((op) => op.opId === options.cursor) + 1
+                : 0;
+            const limit = options.limit ?? 100;
+            const items = matching.slice(Math.max(0, start), Math.max(0, start) + limit);
+            return {
+                items,
+                nextCursor: items.length >= limit ? (items[items.length - 1]?.opId ?? null) : null,
+            };
+        },
+        nextRevision: () => "rev_next",
+        nextOperationId: () => "op_next",
+        nextEventId: () => "evt_next",
+        enqueueWriteback: () => undefined,
+        getPendingWritebacks: () => [],
+        getWorkspaceId: () => "ws_core",
+        listEnvelopes: (_options) => ({
+            items: [],
+            nextCursor: null,
+        }),
+    };
+}
+function compareOperations(left, right) {
+    const leftItem = operationToListItem(left);
+    const rightItem = operationToListItem(right);
+    if (leftItem.nextAttemptAt && rightItem.nextAttemptAt) {
+        const byNextAttempt = leftItem.nextAttemptAt.localeCompare(rightItem.nextAttemptAt);
+        if (byNextAttempt !== 0) {
+            return byNextAttempt;
+        }
+    }
+    else if (leftItem.nextAttemptAt) {
+        return -1;
+    }
+    else if (rightItem.nextAttemptAt) {
+        return 1;
+    }
+    return leftItem.id.localeCompare(rightItem.id);
+}
+function operationToListItem(op) {
+    return {
+        id: op.opId,
+        nextAttemptAt: op.nextAttemptAt,
+    };
+}
+void {};

package/dist/writeback.schemaref.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/writeback.schemaref.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { resolveWritebackSchemaRef } from "./writeback.js";
+describe("resolveWritebackSchemaRef", () => {
+    it("derives the schema id from a writeback path", () => {
+        expect(resolveWritebackSchemaRef(makeStorage(), "/linear/issues/AGE-16__abc/comments/wb-1715000000.json")).toEqual({
+            provider: "linear",
+            resource: "comments",
+            schemaId: "linear/comments.schema.json",
+        });
+    });
+    it("returns null for paths without a resource segment", () => {
+        expect(resolveWritebackSchemaRef(makeStorage(), "/linear/wb.json")).toBeNull();
+    });
+    it("uses a registered schema id when storage provides one", () => {
+        const storage = makeStorage({
+            getWritebackSchemaId: (provider, resource) => `${provider}/${resource}.v2.schema.json`,
+        });
+        expect(resolveWritebackSchemaRef(storage, "/linear/issues/AGE-16__abc/comments/wb.json")?.schemaId).toBe("linear/comments.v2.schema.json");
+    });
+    it("returns null when storage reports no registered schema", () => {
+        const storage = makeStorage({
+            getWritebackSchemaId: () => null,
+        });
+        expect(resolveWritebackSchemaRef(storage, "/linear/issues/AGE-16__abc/comments/wb.json")).toBeNull();
+    });
+});
+function makeStorage(overrides = {}) {
+    return {
+        getFile: () => null,
+        listFiles: () => [],
+        putFile: () => undefined,
+        deleteFile: () => undefined,
+        appendEvent: () => undefined,
+        listEvents: () => ({ items: [], nextCursor: null }),
+        getRecentEvents: () => [],
+        getOperation: () => null,
+        putOperation: () => undefined,
+        listOperations: () => ({
+            items: [],
+            nextCursor: null,
+        }),
+        nextRevision: () => "rev_next",
+        nextOperationId: () => "op_next",
+        nextEventId: () => "evt_next",
+        enqueueWriteback: () => undefined,
+        getPendingWritebacks: () => [],
+        getWorkspaceId: () => "ws_core",
+        ...overrides,
+    };
+}
+void {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/core",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "description": "Shared business logic for relayfile — file operations, ACL, queries, events, and writeback lifecycle",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",