TypeScript

pnpm add @withmarfa/sdk
# or
npm install @withmarfa/sdk
# or
bun add @withmarfa/sdk

import { MarfaClient } from "@withmarfa/sdk";

const client = new MarfaClient({
  url: "https://marfa.example.com",
  apiKey: process.env.MARFA_API_KEY!,
});

interface ClientConfig {
  url: string;
  apiKey: string;
  fetch?: typeof fetch;        // override for custom transport (e.g. retry middleware)
  timeoutMs?: number;          // default 30000
  conflictStrategy?: "auto" | "manual" | "callback";   // default "auto"
  cdnBaseUrl?: string;         // optional CDN prefix for blob URLs
}

const note = await client.items.create({
  type: "core.note",
  properties: { body: "Hello, Marfa", title: "First note" },
  tags: ["intro"],
  tier: "library",
  source_id: "intro-001",        // optional; enables natural-key upsert on re-create
});

const one = await client.items.get(note.id);
const { data, nextCursor } = await client.items.list({
  type: "core.note",
  state: "active",
  limit: 50,
});

await client.items.update(
  note.id,
  { body: "Updated content" },          // properties to merge
  { version: note.version },            // optimistic concurrency, no upfront GET
);

await client.items.transition(note.id, "archived");
await client.items.delete(note.id);         // → trashed
await client.items.restore(note.id);        // ← restore from trashed

await client.items.update(id, { body: "..." }, { version: 7 });

await client.edges.create({
  source_id: note.id,
  target_id: person.id,
  edge_type: "about",
});

const outbound = await client.items.edges(note.id);            // edges from note
const inbound  = await client.items.backrefs(person.id);       // edges to person

// Global tenant-scoped listing across all items, by edge type.
const allReplies = await client.edges.list({ edge_type: "in-thread" });

await client.edges.delete(edgeId);
await client.edges.update(edgeId, { properties: { position: 3 } });

const edgeTypes = await client.edges.types.list();

const highlight = await client.items.create({
  type: "core.highlight",
  properties: { text: "important passage", locator_type: "offset", start_location: 123, end_location: 189 },
  edges: { references: [documentId] },
});

// Admin-only. For third-party flows, prefer natural-key upsert (see above).
await client.items.bulk({ items: payload });
await client.edges.bulk({ edges: edgePayload });
await client.items.bulkAction({ action: "transition", state: "archived", filter: { tags: ["wip"] } });

const result = await client.items.bulkAction(
  { action: "purge", confirm: "PURGE", filter: { type: "core.scratch" } },
  { onProgress: (job) => console.log(`[${job.processed}/${job.matched}]`) },
);

const metadata = await client.metadata.get(note.id);
await client.metadata.addTags(note.id, ["urgent"]);
await client.metadata.removeTag(note.id, "urgent");
await client.metadata.set(note.id, { tags: ["work"] });
await client.metadata.merge(note.id, { tags: ["q2-planning"] });

// Distinct tags across the tenant, with usage counts.
const tags = await client.metadata.listTags();

const { hash } = await client.blobs.upload(fileBytes, "image/png");
const bytes = await client.blobs.download(hash);            // ArrayBuffer
const ok   = await client.blobs.exists(hash);
const url  = client.blobs.url(hash);                        // CDN when configured, API otherwise

const results = await client.search("orwell", { type: "core.bookmark" });
const tagged  = await client.search("orwell", { tags: ["fiction", "classic"] }); // AND

await client.items.update(
  id,
  { body: "..." },
  {
    version: 3,
    conflict: "callback",
    resolve: async ({ current, ancestor, clientPatch, conflictingFields, mergePolicy }) => {
      return { ...current.properties, ...clientPatch };
    },
  },
);

{
  itemId: string;            // the original item
  mergedItemId: string;      // the original item id (post-retry)
  conflictedCopyId?: string; // the new sibling, when keep-both spawned one
  fields: string[];          // the conflicting fields
  strategy: Record<string, "last_writer_wins" | "keep_both_copies">;
                             // per-field: which merge policy resolved each conflict
}

import {
  MarfaError,
  NotFoundError,
  ValidationError,
  ConflictError,
  UnauthorizedError,
  ForbiddenError,
} from "@withmarfa/sdk";

try {
  await client.items.get("bogus");
} catch (err) {
  if (err instanceof NotFoundError) {
    // err.code === "item_not_found"
  }
  throw err;
}

import {
  MarfaAuth,
  startDeviceFlow,
  OAuthError,
  generatePkcePair,
  type TokenProvider,
  MemoryTokenStorage,
  LocalStorageTokenStorage,
} from "@withmarfa/sdk/auth";

const auth = new MarfaAuth({
  baseUrl: "https://marfa.example.com",
  clientId: "my-app",
  redirectUri: "https://myapp.example.com/oauth/callback",
  scope: ["core.note:read", "core.note:write"],
  storage: new LocalStorageTokenStorage("my-app.tokens"),
});

// 1. Send the user to authorize
window.location.href = await auth.buildAuthorizeUrl();

// 2. On redirect back, exchange the `code` query param
const tokens = await auth.handleCallback(window.location.href);

// 3. Use the access token. Auto-refresh on 401 via a TokenProvider:
const tokenProvider: TokenProvider = () => auth.getAccessToken();
const client = new MarfaClient({
  url: "https://marfa.example.com",
  tokenProvider,                     // alternative to a static apiKey
});

import { startDeviceFlow } from "@withmarfa/sdk/auth";

const session = await startDeviceFlow({
  baseUrl: "https://marfa.example.com",
  clientId: "my-cli",
  scope: ["core.bookmark:read"],
});

console.log(`Open ${session.verificationUri} and enter ${session.userCode}`);
const tokens = await session.poll();   // resolves once the user approves

import { verifyWebhookSignature } from "@withmarfa/sdk";

const ok = await verifyWebhookSignature({
  body: rawRequestBody,         // ArrayBuffer or string
  headers: incomingHeaders,
  secret: subscriptionSecret,
});