@obsidianlabs/writeback-core

React hooks and fetch client for consuming a writeback worker API. Built on TanStack Query with optimistic updates, conflict detection, and D1 bookmark tracking.

Install

pnpm add @obsidianlabs/writeback-core

Usage

import { WritebackProvider, useEntity, useEntityMutation } from "@obsidianlabs/writeback-core";

function App() {
  return (
    <WritebackProvider apiUrl="https://api.example.com">
      <InvoiceEditor id="inv-123" />
    </WritebackProvider>
  );
}

function InvoiceEditor({ id }: { id: string }) {
  const { data, isLoading } = useEntity("invoice", id);
  const { update, conflict } = useEntityMutation("invoice");

  if (isLoading) return <div>Loading...</div>;
  if (!data) return <div>Not found</div>;

  return (
    <div>
      <p>Status: {data.status}</p>
      <button onClick={() => update({
        id,
        expectedVersion: data.__version,
        changes: { status: "paid" },
      })}>
        Mark Paid
      </button>
      {conflict && <p>Conflict! Someone else modified this.</p>}
    </div>
  );
}

API

<WritebackProvider>

Wraps your app with a React Query client and fetch client.

| Prop | Type | Description | |---|---|---| | apiUrl | string | Base URL of the writeback worker | | queryClient | QueryClient? | Optional custom React Query client |

useEntity(type, id)

Fetches a single entity by type and ID.

Returns { data, isLoading, error, refetch }.

useEntityList(type, filters?)

Fetches a list of entities with optional filters.

Returns { data, isLoading, error, refetch }.

useEntityMutation(type)

Provides create, update, and remove mutation functions.

Returns { create, update, remove, isPending, error, conflict }.

useAuth()

Auth state and actions for magic-link or Access auth.

Returns { user, isLoading, signIn?, signOut }.

License

MIT