@singi-labs/sifa-sdk 0.5.0 → 0.6.0

package/dist/query/index.cjs

@@ -0,0 +1,161 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+var reactQuery = require('@tanstack/react-query');
+
+// src/query/client.ts
+var ApiError = class extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var DEFAULT_TIMEOUT_MS = 1e4;
+var MAX_RATE_LIMIT_RETRIES = 3;
+var RATE_LIMIT_RETRY_CAP_SECONDS = 3;
+async function apiFetch(config, path, options = {}) {
+  const fetchFn = config.fetch ?? globalThis.fetch;
+  const url = `${config.baseUrl}${path}`;
+  const maxRetries = options.retryOn429 ? MAX_RATE_LIMIT_RETRIES : 0;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const signal = options.signal ?? AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const headers = { ...options.headers ?? {} };
+    let body;
+    if (options.body !== void 0) {
+      headers["Content-Type"] ??= "application/json";
+      body = JSON.stringify(options.body);
+    }
+    const init = {
+      method: options.method ?? "GET",
+      headers,
+      body,
+      signal,
+      credentials: options.credentials,
+      cache: options.cache,
+      ...options.next ? { next: options.next } : {}
+    };
+    const res = await fetchFn(url, init);
+    if (res.status === 429 && attempt < maxRetries) {
+      const retryAfterRaw = res.headers.get("retry-after");
+      const retryAfter = retryAfterRaw ? Number.parseInt(retryAfterRaw, 10) : 2;
+      const waitSeconds = Math.min(
+        Number.isFinite(retryAfter) ? retryAfter : 2,
+        RATE_LIMIT_RETRY_CAP_SECONDS
+      );
+      await new Promise((r) => setTimeout(r, waitSeconds * 1e3));
+      continue;
+    }
+    if (!res.ok) {
+      let errBody;
+      try {
+        errBody = await res.json();
+      } catch {
+        try {
+          errBody = await res.text();
+        } catch {
+          errBody = void 0;
+        }
+      }
+      throw new ApiError(`Sifa API ${res.status} on ${path}`, res.status, errBody);
+    }
+    return await res.json();
+  }
+  throw new ApiError(`Sifa API exhausted retries on ${path}`, 429);
+}
+async function apiFetchOrNull(config, path, options = {}) {
+  try {
+    return await apiFetch(config, path, options);
+  } catch (e) {
+    if (e instanceof ApiError && e.status === 404) return null;
+    throw e;
+  }
+}
+var SifaConfigContext = react.createContext(null);
+function SifaProvider({ config, children }) {
+  return /* @__PURE__ */ jsxRuntime.jsx(SifaConfigContext.Provider, { value: config, children });
+}
+function useSifaConfig() {
+  const ctx = react.useContext(SifaConfigContext);
+  if (!ctx) {
+    throw new Error(
+      "useSifaConfig must be used inside <SifaProvider>. Wrap your app once with <SifaProvider config={...}>."
+    );
+  }
+  return ctx;
+}
+
+// src/query/fetchers/profile.ts
+function fetchProfile(config, handleOrDid, options = {}) {
+  const path = `/api/profile/${encodeURIComponent(handleOrDid)}`;
+  return apiFetchOrNull(config, path, {
+    retryOn429: true,
+    ...options
+  });
+}
+
+// src/query/fetchers/positions.ts
+function createPosition(config, data, options = {}) {
+  return apiFetch(config, "/api/positions", {
+    method: "POST",
+    body: data,
+    credentials: "include",
+    ...options
+  });
+}
+
+// src/query/keys.ts
+var sifaQueryKeys = {
+  all: () => ["sifa"],
+  profile: {
+    all: () => ["sifa", "profile"],
+    byHandle: (handleOrDid) => ["sifa", "profile", handleOrDid]
+  },
+  position: {
+    all: () => ["sifa", "position"],
+    byOwner: (did) => ["sifa", "position", "by-owner", did]
+  }
+};
+
+// src/query/hooks/use-create-position.ts
+function useCreatePosition(ownerDid, options) {
+  const config = useSifaConfig();
+  const queryClient = reactQuery.useQueryClient();
+  return reactQuery.useMutation({
+    mutationFn: (data) => createPosition(config, data),
+    onSuccess: async (result, variables, onMutateResult, context) => {
+      if (result.success) {
+        await queryClient.invalidateQueries({ queryKey: sifaQueryKeys.profile.byHandle(ownerDid) });
+        await queryClient.invalidateQueries({ queryKey: sifaQueryKeys.position.byOwner(ownerDid) });
+      }
+      await options?.onSuccess?.(result, variables, onMutateResult, context);
+    },
+    ...options
+  });
+}
+function useProfile(handleOrDid, options) {
+  const config = useSifaConfig();
+  return reactQuery.useQuery({
+    queryKey: sifaQueryKeys.profile.byHandle(handleOrDid ?? ""),
+    queryFn: () => fetchProfile(config, handleOrDid ?? ""),
+    enabled: Boolean(handleOrDid) && (options?.enabled ?? true),
+    ...options
+  });
+}
+
+exports.ApiError = ApiError;
+exports.SifaProvider = SifaProvider;
+exports.apiFetch = apiFetch;
+exports.apiFetchOrNull = apiFetchOrNull;
+exports.createPosition = createPosition;
+exports.fetchProfile = fetchProfile;
+exports.sifaQueryKeys = sifaQueryKeys;
+exports.useCreatePosition = useCreatePosition;
+exports.useProfile = useProfile;
+exports.useSifaConfig = useSifaConfig;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/query/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/query/client.ts","../../src/query/config.tsx","../../src/query/fetchers/profile.ts","../../src/query/fetchers/positions.ts","../../src/query/keys.ts","../../src/query/hooks/use-create-position.ts","../../src/query/hooks/use-profile.ts"],"names":["createContext","useContext","useQueryClient","useMutation","useQuery"],"mappings":";;;;;;;AA2CO,IAAM,QAAA,GAAN,cAAuB,KAAA,CAAM;AAAA,EACzB,MAAA;AAAA,EACA,IAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAiB,MAAA,EAAgB,IAAA,EAAgB;AAC3D,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,UAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AACF;AAEA,IAAM,kBAAA,GAAqB,GAAA;AAC3B,IAAM,sBAAA,GAAyB,CAAA;AAC/B,IAAM,4BAAA,GAA+B,CAAA;AASrC,eAAsB,QAAA,CACpB,MAAA,EACA,IAAA,EACA,OAAA,GAA2B,EAAC,EAChB;AACZ,EAAA,MAAM,OAAA,GAAU,MAAA,CAAO,KAAA,IAAS,UAAA,CAAW,KAAA;AAC3C,EAAA,MAAM,GAAA,GAAM,CAAA,EAAG,MAAA,CAAO,OAAO,GAAG,IAAI,CAAA,CAAA;AACpC,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,UAAA,GAAa,sBAAA,GAAyB,CAAA;AAEjE,EAAA,KAAA,IAAS,OAAA,GAAU,CAAA,EAAG,OAAA,IAAW,UAAA,EAAY,OAAA,EAAA,EAAW;AACtD,IAAA,MAAM,SAAS,OAAA,CAAQ,MAAA,IAAU,YAAY,OAAA,CAAQ,OAAA,CAAQ,aAAa,kBAAkB,CAAA;AAE5F,IAAA,MAAM,UAAkC,EAAE,GAAI,OAAA,CAAQ,OAAA,IAAW,EAAC,EAAG;AACrE,IAAA,IAAI,IAAA;AACJ,IAAA,IAAI,OAAA,CAAQ,SAAS,MAAA,EAAW;AAC9B,MAAA,OAAA,CAAQ,cAAc,CAAA,KAAM,kBAAA;AAC5B,MAAA,IAAA,GAAO,IAAA,CAAK,SAAA,CAAU,OAAA,CAAQ,IAAI,CAAA;AAAA,IACpC;AAGA,IAAA,MAAM,IAAA,GAAO;AAAA,MACX,MAAA,EAAQ,QAAQ,MAAA,IAAU,KAAA;AAAA,MAC1B,OAAA;AAAA,MACA,IAAA;AAAA,MACA,MAAA;AAAA,MACA,aAAa,OAAA,CAAQ,WAAA;AAAA,MACrB,OAAO,OAAA,CAAQ,KAAA;AAAA,MACf,GAAI,QAAQ,IAAA,GAAO,EAAE,MAAM,OAAA,CAAQ,IAAA,KAAS;AAAC,KAC/C;AAEA,IAAA,MAAM,GAAA,GAAM,MAAM,OAAA,CAAQ,GAAA,EAAK,IAAI,CAAA;AAEnC,IAAA,IAAI,GAAA,CAAI,MAAA,KAAW,GAAA,IAAO,OAAA,GAAU,UAAA,EAAY;AAC9C,MAAA,MAAM,aAAA,GAAgB,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,aAAa,CAAA;AACnD,MAAA,MAAM,aAAa,aAAA,GAAgB,MAAA,CAAO,QAAA,CAAS,aAAA,EAAe,EAAE,CAAA,GAAI,CAAA;AACxE,MAAA,MAAM,cAAc,IAAA,CAAK,GAAA;AAAA,QACvB,MAAA,CAAO,QAAA,CAAS,UAAU,CAAA,GAAI,UAAA,GAAa,CAAA;AAAA,QAC3C;AAAA,OACF;AACA,MAAA,MAAM,IAAI,QAAQ,CAAC,CAAA,KAAM,WAAW,CAAA,EAAG,WAAA,GAAc,GAAI,CAAC,CAAA;AAC1D,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,CAAC,IAAI,EAAA,EAAI;AACX,MAAA,IAAI,OAAA;AACJ,MAAA,IAAI;AACF,QAAA,OAAA,GAAW,MAAM,IAAI,IAAA,EAAK;AAAA,MAC5B,CAAA,CAAA,MAAQ;AACN,QAAA,IAAI;AACF,UAAA,OAAA,GAAU,MAAM,IAAI,IAAA,EAAK;AAAA,QAC3B,CAAA,CAAA,MAAQ;AACN,UAAA,OAAA,GAAU,MAAA;AAAA,QACZ;AAAA,MACF;AACA,MAAA,MAAM,IAAI,QAAA,CAAS,CAAA,SAAA,EAAY,GAAA,CAAI,MAAM,OAAO,IAAI,CAAA,CAAA,EAAI,GAAA,CAAI,MAAA,EAAQ,OAAO,CAAA;AAAA,IAC7E;AAEA,IAAA,OAAQ,MAAM,IAAI,IAAA,EAAK;AAAA,EACzB;AAEA,EAAA,MAAM,IAAI,QAAA,CAAS,CAAA,8BAAA,EAAiC,IAAI,IAAI,GAAG,CAAA;AACjE;AAOA,eAAsB,cAAA,CACpB,MAAA,EACA,IAAA,EACA,OAAA,GAA2B,EAAC,EACT;AACnB,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,QAAA,CAAY,MAAA,EAAQ,IAAA,EAAM,OAAO,CAAA;AAAA,EAChD,SAAS,CAAA,EAAG;AACV,IAAA,IAAI,CAAA,YAAa,QAAA,IAAY,CAAA,CAAE,MAAA,KAAW,KAAK,OAAO,IAAA;AACtD,IAAA,MAAM,CAAA;AAAA,EACR;AACF;AC3IA,IAAM,iBAAA,GAAoBA,oBAAoC,IAAI,CAAA;AAoB3D,SAAS,YAAA,CAAa,EAAE,MAAA,EAAQ,QAAA,EAAS,EAAsB;AACpE,EAAA,sCAAQ,iBAAA,CAAkB,QAAA,EAAlB,EAA2B,KAAA,EAAO,QAAS,QAAA,EAAS,CAAA;AAC9D;AAMO,SAAS,aAAA,GAA+B;AAC7C,EAAA,MAAM,GAAA,GAAMC,iBAAW,iBAAiB,CAAA;AACxC,EAAA,IAAI,CAAC,GAAA,EAAK;AACR,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT;;;AC/BO,SAAS,YAAA,CACd,MAAA,EACA,WAAA,EACA,OAAA,GAA2B,EAAC,EACH;AACzB,EAAA,MAAM,IAAA,GAAO,CAAA,aAAA,EAAgB,kBAAA,CAAmB,WAAW,CAAC,CAAA,CAAA;AAC5D,EAAA,OAAO,cAAA,CAAwB,QAAQ,IAAA,EAAM;AAAA,IAC3C,UAAA,EAAY,IAAA;AAAA,IACZ,GAAG;AAAA,GACJ,CAAA;AACH;;;ACEO,SAAS,cAAA,CACd,MAAA,EACA,IAAA,EACA,OAAA,GAA2B,EAAC,EACL;AACvB,EAAA,OAAO,QAAA,CAAuB,QAAQ,gBAAA,EAAkB;AAAA,IACtD,MAAA,EAAQ,MAAA;AAAA,IACR,IAAA,EAAM,IAAA;AAAA,IACN,WAAA,EAAa,SAAA;AAAA,IACb,GAAG;AAAA,GACJ,CAAA;AACH;;;ACvBO,IAAM,aAAA,GAAgB;AAAA,EAC3B,GAAA,EAAK,MAAM,CAAC,MAAM,CAAA;AAAA,EAElB,OAAA,EAAS;AAAA,IACP,GAAA,EAAK,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA;AAAA,IAC7B,UAAU,CAAC,WAAA,KAAwB,CAAC,MAAA,EAAQ,WAAW,WAAW;AAAA,GACpE;AAAA,EAEA,QAAA,EAAU;AAAA,IACR,GAAA,EAAK,MAAM,CAAC,MAAA,EAAQ,UAAU,CAAA;AAAA,IAC9B,SAAS,CAAC,GAAA,KAAgB,CAAC,MAAA,EAAQ,UAAA,EAAY,YAAY,GAAG;AAAA;AAElE;;;ACPO,SAAS,iBAAA,CACd,UACA,OAAA,EACA;AACA,EAAA,MAAM,SAAS,aAAA,EAAc;AAC7B,EAAA,MAAM,cAAcC,yBAAA,EAAe;AAEnC,EAAA,OAAOC,sBAAA,CAAY;AAAA,IACjB,UAAA,EAAY,CAAC,IAAA,KAAkC,cAAA,CAAe,QAAQ,IAAI,CAAA;AAAA,IAC1E,SAAA,EAAW,OAAO,MAAA,EAAQ,SAAA,EAAW,gBAAgB,OAAA,KAAY;AAC/D,MAAA,IAAI,OAAO,OAAA,EAAS;AAClB,QAAA,MAAM,WAAA,CAAY,kBAAkB,EAAE,QAAA,EAAU,cAAc,OAAA,CAAQ,QAAA,CAAS,QAAQ,CAAA,EAAG,CAAA;AAC1F,QAAA,MAAM,WAAA,CAAY,kBAAkB,EAAE,QAAA,EAAU,cAAc,QAAA,CAAS,OAAA,CAAQ,QAAQ,CAAA,EAAG,CAAA;AAAA,MAC5F;AACA,MAAA,MAAM,OAAA,EAAS,SAAA,GAAY,MAAA,EAAQ,SAAA,EAAW,gBAAgB,OAAO,CAAA;AAAA,IACvE,CAAA;AAAA,IACA,GAAG;AAAA,GACJ,CAAA;AACH;AClBO,SAAS,UAAA,CACd,aACA,OAAA,EASA;AACA,EAAA,MAAM,SAAS,aAAA,EAAc;AAC7B,EAAA,OAAOC,mBAAA,CAAS;AAAA,IACd,QAAA,EAAU,aAAA,CAAc,OAAA,CAAQ,QAAA,CAAS,eAAe,EAAE,CAAA;AAAA,IAC1D,OAAA,EAAS,MAAM,YAAA,CAAa,MAAA,EAAQ,eAAe,EAAE,CAAA;AAAA,IACrD,OAAA,EAAS,OAAA,CAAQ,WAAW,CAAA,KAAM,SAAS,OAAA,IAAW,IAAA,CAAA;AAAA,IACtD,GAAG;AAAA,GACJ,CAAA;AACH","file":"index.cjs","sourcesContent":["/**\n * Foundation HTTP client for talking to the Sifa AppView.\n *\n * Stateless. Consumers supply a {@link SifaApiConfig} per call (the React\n * hooks read it from context; non-React consumers pass it explicitly). No\n * singletons, no module-level state.\n */\n\n/** Configuration passed to every fetcher. */\nexport interface SifaApiConfig {\n  /** Base URL of the sifa-api AppView, e.g. `https://api.sifa.id`. No trailing slash. */\n  baseUrl: string;\n  /**\n   * Optional fetch implementation. Defaults to {@link globalThis.fetch}.\n   * Lets Next.js consumers pass their cache-enhanced fetch; node/Expo\n   * consumers can leave this unset.\n   */\n  fetch?: typeof fetch;\n}\n\n/** Options accepted by {@link apiFetch}. */\nexport interface ApiFetchOptions {\n  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';\n  /** Request body. Serialized to JSON automatically. */\n  body?: unknown;\n  /** AbortSignal. Defaults to `AbortSignal.timeout(timeoutMs)` if `timeoutMs` is set. */\n  signal?: AbortSignal;\n  /** Per-call timeout in milliseconds. Default: 10_000. Ignored if `signal` is provided. */\n  timeoutMs?: number;\n  /** Retry on HTTP 429 up to 3 times with the server's `Retry-After` delay (capped at 3s). */\n  retryOn429?: boolean;\n  /** Additional headers. `Content-Type: application/json` is set automatically when `body` is present. */\n  headers?: Record<string, string>;\n  credentials?: RequestCredentials;\n  cache?: RequestCache;\n  /**\n   * Next.js-specific cache hints. Ignored on non-Next runtimes. Passed\n   * through transparently as part of {@link RequestInit}.\n   */\n  next?: { revalidate?: number | false; tags?: string[] };\n}\n\n/** Error thrown by {@link apiFetch} on non-2xx responses. */\nexport class ApiError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n\n  constructor(message: string, status: number, body?: unknown) {\n    super(message);\n    this.name = 'ApiError';\n    this.status = status;\n    this.body = body;\n  }\n}\n\nconst DEFAULT_TIMEOUT_MS = 10_000;\nconst MAX_RATE_LIMIT_RETRIES = 3;\nconst RATE_LIMIT_RETRY_CAP_SECONDS = 3;\n\n/**\n * Generic fetcher used by all SDK query and mutation functions.\n *\n * Returns parsed JSON typed as `T`. Throws {@link ApiError} on non-2xx\n * responses. Use {@link apiFetchOrNull} when 404 should resolve to `null`\n * instead.\n */\nexport async function apiFetch<T = unknown>(\n  config: SifaApiConfig,\n  path: string,\n  options: ApiFetchOptions = {},\n): Promise<T> {\n  const fetchFn = config.fetch ?? globalThis.fetch;\n  const url = `${config.baseUrl}${path}`;\n  const maxRetries = options.retryOn429 ? MAX_RATE_LIMIT_RETRIES : 0;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    const signal = options.signal ?? AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS);\n\n    const headers: Record<string, string> = { ...(options.headers ?? {}) };\n    let body: BodyInit | undefined;\n    if (options.body !== undefined) {\n      headers['Content-Type'] ??= 'application/json';\n      body = JSON.stringify(options.body);\n    }\n\n    // `next` is a Next.js extension to RequestInit; cast through.\n    const init = {\n      method: options.method ?? 'GET',\n      headers,\n      body,\n      signal,\n      credentials: options.credentials,\n      cache: options.cache,\n      ...(options.next ? { next: options.next } : {}),\n    } as RequestInit;\n\n    const res = await fetchFn(url, init);\n\n    if (res.status === 429 && attempt < maxRetries) {\n      const retryAfterRaw = res.headers.get('retry-after');\n      const retryAfter = retryAfterRaw ? Number.parseInt(retryAfterRaw, 10) : 2;\n      const waitSeconds = Math.min(\n        Number.isFinite(retryAfter) ? retryAfter : 2,\n        RATE_LIMIT_RETRY_CAP_SECONDS,\n      );\n      await new Promise((r) => setTimeout(r, waitSeconds * 1000));\n      continue;\n    }\n\n    if (!res.ok) {\n      let errBody: unknown;\n      try {\n        errBody = (await res.json()) as unknown;\n      } catch {\n        try {\n          errBody = await res.text();\n        } catch {\n          errBody = undefined;\n        }\n      }\n      throw new ApiError(`Sifa API ${res.status} on ${path}`, res.status, errBody);\n    }\n\n    return (await res.json()) as T;\n  }\n\n  throw new ApiError(`Sifa API exhausted retries on ${path}`, 429);\n}\n\n/**\n * Variant of {@link apiFetch} that resolves to `null` on HTTP 404 instead\n * of throwing. Useful for \"fetch by handle\" reads where missing is\n * expected (e.g. unknown profile).\n */\nexport async function apiFetchOrNull<T>(\n  config: SifaApiConfig,\n  path: string,\n  options: ApiFetchOptions = {},\n): Promise<T | null> {\n  try {\n    return await apiFetch<T>(config, path, options);\n  } catch (e) {\n    if (e instanceof ApiError && e.status === 404) return null;\n    throw e;\n  }\n}\n","'use client';\n\nimport { createContext, useContext, type ReactNode } from 'react';\n\nimport type { SifaApiConfig } from './client.js';\n\nconst SifaConfigContext = createContext<SifaApiConfig | null>(null);\n\nexport interface SifaProviderProps {\n  config: SifaApiConfig;\n  children: ReactNode;\n}\n\n/**\n * Provides the {@link SifaApiConfig} that hooks under it can read via\n * {@link useSifaConfig}. Wrap the React tree once; hooks consume it.\n *\n * @example\n * ```tsx\n * <QueryClientProvider client={queryClient}>\n *   <SifaProvider config={{ baseUrl: process.env.NEXT_PUBLIC_API_URL! }}>\n *     <App />\n *   </SifaProvider>\n * </QueryClientProvider>\n * ```\n */\nexport function SifaProvider({ config, children }: SifaProviderProps) {\n  return <SifaConfigContext.Provider value={config}>{children}</SifaConfigContext.Provider>;\n}\n\n/**\n * Read the SDK's {@link SifaApiConfig} from context. Throws if no\n * {@link SifaProvider} is mounted above.\n */\nexport function useSifaConfig(): SifaApiConfig {\n  const ctx = useContext(SifaConfigContext);\n  if (!ctx) {\n    throw new Error(\n      'useSifaConfig must be used inside <SifaProvider>. Wrap your app once with <SifaProvider config={...}>.',\n    );\n  }\n  return ctx;\n}\n","import type { Profile } from '../../types/index.js';\nimport { apiFetchOrNull, type ApiFetchOptions, type SifaApiConfig } from '../client.js';\n\n/**\n * Read the aggregated profile for a handle or DID.\n *\n * Returns `null` when the AppView has no profile for the given identifier\n * (HTTP 404). Throws {@link ApiError} on other non-2xx responses.\n *\n * Server-callable (Next.js RSC) and client-callable (Expo, browser).\n */\nexport function fetchProfile(\n  config: SifaApiConfig,\n  handleOrDid: string,\n  options: ApiFetchOptions = {},\n): Promise<Profile | null> {\n  const path = `/api/profile/${encodeURIComponent(handleOrDid)}`;\n  return apiFetchOrNull<Profile>(config, path, {\n    retryOn429: true,\n    ...options,\n  });\n}\n","import { apiFetch, type ApiFetchOptions, type SifaApiConfig } from '../client.js';\n\n/** Result returned by record-write mutations (create / update / delete). */\nexport interface WriteResult {\n  success: boolean;\n  error?: string;\n  pdsHost?: string;\n}\n\n/** Result returned by create mutations. Includes the newly created `rkey`. */\nexport interface CreateResult extends WriteResult {\n  rkey?: string;\n}\n\n/**\n * Create a new `id.sifa.profile.position` record on the authenticated\n * user's PDS. The AppView signs and writes via the user's OAuth session.\n *\n * `data` should be a lexicon-shaped position record (without `createdAt`\n * or `rkey`; the AppView fills both). Validate with\n * `ProfilePositionRecordSchema.omit({ createdAt: true })` before calling\n * if you want client-side guarantees.\n */\nexport function createPosition(\n  config: SifaApiConfig,\n  data: Record<string, unknown>,\n  options: ApiFetchOptions = {},\n): Promise<CreateResult> {\n  return apiFetch<CreateResult>(config, '/api/positions', {\n    method: 'POST',\n    body: data,\n    credentials: 'include',\n    ...options,\n  });\n}\n","/**\n * Query key factory for TanStack Query.\n *\n * Keys are read-only tuples; the hierarchy matches the SDK's fetcher\n * grouping. Use these instead of inline arrays so consumers can target\n * `queryClient.invalidateQueries({ queryKey: keys.profile.all() })` and\n * similar patterns without typos.\n *\n * Convention: every leaf key starts with the namespace ('sifa') so\n * consumers can invalidate everything Sifa-related in one call.\n */\nexport const sifaQueryKeys = {\n  all: () => ['sifa'] as const,\n\n  profile: {\n    all: () => ['sifa', 'profile'] as const,\n    byHandle: (handleOrDid: string) => ['sifa', 'profile', handleOrDid] as const,\n  },\n\n  position: {\n    all: () => ['sifa', 'position'] as const,\n    byOwner: (did: string) => ['sifa', 'position', 'by-owner', did] as const,\n  },\n} as const;\n\nexport type SifaQueryKey =\n  | ReturnType<typeof sifaQueryKeys.all>\n  | ReturnType<typeof sifaQueryKeys.profile.all>\n  | ReturnType<typeof sifaQueryKeys.profile.byHandle>\n  | ReturnType<typeof sifaQueryKeys.position.all>\n  | ReturnType<typeof sifaQueryKeys.position.byOwner>;\n","'use client';\n\nimport { useMutation, useQueryClient, type UseMutationOptions } from '@tanstack/react-query';\n\nimport { useSifaConfig } from '../config.js';\nimport { createPosition, type CreateResult } from '../fetchers/positions.js';\nimport { sifaQueryKeys } from '../keys.js';\n\n/**\n * React hook for creating a new position record. On success, invalidates\n * the owner's profile cache so the new position is reflected on the next\n * read.\n *\n * The owner DID is required so the mutation can target the correct\n * profile cache entry for invalidation.\n */\nexport function useCreatePosition(\n  ownerDid: string,\n  options?: Omit<UseMutationOptions<CreateResult, Error, Record<string, unknown>>, 'mutationFn'>,\n) {\n  const config = useSifaConfig();\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn: (data: Record<string, unknown>) => createPosition(config, data),\n    onSuccess: async (result, variables, onMutateResult, context) => {\n      if (result.success) {\n        await queryClient.invalidateQueries({ queryKey: sifaQueryKeys.profile.byHandle(ownerDid) });\n        await queryClient.invalidateQueries({ queryKey: sifaQueryKeys.position.byOwner(ownerDid) });\n      }\n      await options?.onSuccess?.(result, variables, onMutateResult, context);\n    },\n    ...options,\n  });\n}\n","'use client';\n\nimport { useQuery, type UseQueryOptions } from '@tanstack/react-query';\n\nimport type { Profile } from '../../types/index.js';\nimport { useSifaConfig } from '../config.js';\nimport { fetchProfile } from '../fetchers/profile.js';\nimport { sifaQueryKeys } from '../keys.js';\n\n/**\n * React hook that reads an aggregated profile by handle or DID via\n * TanStack Query. Returns `null` data when the profile does not exist.\n *\n * Pass `{ enabled: false }` (or an empty `handleOrDid`) to defer the\n * fetch.\n */\nexport function useProfile(\n  handleOrDid: string | undefined | null,\n  options?: Omit<\n    UseQueryOptions<\n      Profile | null,\n      Error,\n      Profile | null,\n      ReturnType<typeof sifaQueryKeys.profile.byHandle>\n    >,\n    'queryKey' | 'queryFn'\n  >,\n) {\n  const config = useSifaConfig();\n  return useQuery({\n    queryKey: sifaQueryKeys.profile.byHandle(handleOrDid ?? ''),\n    queryFn: () => fetchProfile(config, handleOrDid ?? ''),\n    enabled: Boolean(handleOrDid) && (options?.enabled ?? true),\n    ...options,\n  });\n}\n"]}

package/dist/query/index.d.cts

@@ -0,0 +1,168 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { P as Profile } from '../index-IDRpze8y.cjs';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
+
+/**
+ * Foundation HTTP client for talking to the Sifa AppView.
+ *
+ * Stateless. Consumers supply a {@link SifaApiConfig} per call (the React
+ * hooks read it from context; non-React consumers pass it explicitly). No
+ * singletons, no module-level state.
+ */
+/** Configuration passed to every fetcher. */
+interface SifaApiConfig {
+    /** Base URL of the sifa-api AppView, e.g. `https://api.sifa.id`. No trailing slash. */
+    baseUrl: string;
+    /**
+     * Optional fetch implementation. Defaults to {@link globalThis.fetch}.
+     * Lets Next.js consumers pass their cache-enhanced fetch; node/Expo
+     * consumers can leave this unset.
+     */
+    fetch?: typeof fetch;
+}
+/** Options accepted by {@link apiFetch}. */
+interface ApiFetchOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body. Serialized to JSON automatically. */
+    body?: unknown;
+    /** AbortSignal. Defaults to `AbortSignal.timeout(timeoutMs)` if `timeoutMs` is set. */
+    signal?: AbortSignal;
+    /** Per-call timeout in milliseconds. Default: 10_000. Ignored if `signal` is provided. */
+    timeoutMs?: number;
+    /** Retry on HTTP 429 up to 3 times with the server's `Retry-After` delay (capped at 3s). */
+    retryOn429?: boolean;
+    /** Additional headers. `Content-Type: application/json` is set automatically when `body` is present. */
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+    /**
+     * Next.js-specific cache hints. Ignored on non-Next runtimes. Passed
+     * through transparently as part of {@link RequestInit}.
+     */
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/** Error thrown by {@link apiFetch} on non-2xx responses. */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Generic fetcher used by all SDK query and mutation functions.
+ *
+ * Returns parsed JSON typed as `T`. Throws {@link ApiError} on non-2xx
+ * responses. Use {@link apiFetchOrNull} when 404 should resolve to `null`
+ * instead.
+ */
+declare function apiFetch<T = unknown>(config: SifaApiConfig, path: string, options?: ApiFetchOptions): Promise<T>;
+/**
+ * Variant of {@link apiFetch} that resolves to `null` on HTTP 404 instead
+ * of throwing. Useful for "fetch by handle" reads where missing is
+ * expected (e.g. unknown profile).
+ */
+declare function apiFetchOrNull<T>(config: SifaApiConfig, path: string, options?: ApiFetchOptions): Promise<T | null>;
+
+interface SifaProviderProps {
+    config: SifaApiConfig;
+    children: ReactNode;
+}
+/**
+ * Provides the {@link SifaApiConfig} that hooks under it can read via
+ * {@link useSifaConfig}. Wrap the React tree once; hooks consume it.
+ *
+ * @example
+ * ```tsx
+ * <QueryClientProvider client={queryClient}>
+ *   <SifaProvider config={{ baseUrl: process.env.NEXT_PUBLIC_API_URL! }}>
+ *     <App />
+ *   </SifaProvider>
+ * </QueryClientProvider>
+ * ```
+ */
+declare function SifaProvider({ config, children }: SifaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Read the SDK's {@link SifaApiConfig} from context. Throws if no
+ * {@link SifaProvider} is mounted above.
+ */
+declare function useSifaConfig(): SifaApiConfig;
+
+/**
+ * Read the aggregated profile for a handle or DID.
+ *
+ * Returns `null` when the AppView has no profile for the given identifier
+ * (HTTP 404). Throws {@link ApiError} on other non-2xx responses.
+ *
+ * Server-callable (Next.js RSC) and client-callable (Expo, browser).
+ */
+declare function fetchProfile(config: SifaApiConfig, handleOrDid: string, options?: ApiFetchOptions): Promise<Profile | null>;
+
+/** Result returned by record-write mutations (create / update / delete). */
+interface WriteResult {
+    success: boolean;
+    error?: string;
+    pdsHost?: string;
+}
+/** Result returned by create mutations. Includes the newly created `rkey`. */
+interface CreateResult extends WriteResult {
+    rkey?: string;
+}
+/**
+ * Create a new `id.sifa.profile.position` record on the authenticated
+ * user's PDS. The AppView signs and writes via the user's OAuth session.
+ *
+ * `data` should be a lexicon-shaped position record (without `createdAt`
+ * or `rkey`; the AppView fills both). Validate with
+ * `ProfilePositionRecordSchema.omit({ createdAt: true })` before calling
+ * if you want client-side guarantees.
+ */
+declare function createPosition(config: SifaApiConfig, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+
+/**
+ * React hook for creating a new position record. On success, invalidates
+ * the owner's profile cache so the new position is reflected on the next
+ * read.
+ *
+ * The owner DID is required so the mutation can target the correct
+ * profile cache entry for invalidation.
+ */
+declare function useCreatePosition(ownerDid: string, options?: Omit<UseMutationOptions<CreateResult, Error, Record<string, unknown>>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<CreateResult, Error, Record<string, unknown>, unknown>;
+
+/**
+ * Query key factory for TanStack Query.
+ *
+ * Keys are read-only tuples; the hierarchy matches the SDK's fetcher
+ * grouping. Use these instead of inline arrays so consumers can target
+ * `queryClient.invalidateQueries({ queryKey: keys.profile.all() })` and
+ * similar patterns without typos.
+ *
+ * Convention: every leaf key starts with the namespace ('sifa') so
+ * consumers can invalidate everything Sifa-related in one call.
+ */
+declare const sifaQueryKeys: {
+    readonly all: () => readonly ["sifa"];
+    readonly profile: {
+        readonly all: () => readonly ["sifa", "profile"];
+        readonly byHandle: (handleOrDid: string) => readonly ["sifa", "profile", string];
+    };
+    readonly position: {
+        readonly all: () => readonly ["sifa", "position"];
+        readonly byOwner: (did: string) => readonly ["sifa", "position", "by-owner", string];
+    };
+};
+type SifaQueryKey = ReturnType<typeof sifaQueryKeys.all> | ReturnType<typeof sifaQueryKeys.profile.all> | ReturnType<typeof sifaQueryKeys.profile.byHandle> | ReturnType<typeof sifaQueryKeys.position.all> | ReturnType<typeof sifaQueryKeys.position.byOwner>;
+
+/**
+ * React hook that reads an aggregated profile by handle or DID via
+ * TanStack Query. Returns `null` data when the profile does not exist.
+ *
+ * Pass `{ enabled: false }` (or an empty `handleOrDid`) to defer the
+ * fetch.
+ */
+declare function useProfile(handleOrDid: string | undefined | null, options?: Omit<UseQueryOptions<Profile | null, Error, Profile | null, ReturnType<typeof sifaQueryKeys.profile.byHandle>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<Profile | null, Error>;
+
+export { ApiError, type ApiFetchOptions, type CreateResult, type SifaApiConfig, SifaProvider, type SifaProviderProps, type SifaQueryKey, type WriteResult, apiFetch, apiFetchOrNull, createPosition, fetchProfile, sifaQueryKeys, useCreatePosition, useProfile, useSifaConfig };

package/dist/query/index.d.ts

@@ -0,0 +1,168 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { P as Profile } from '../index-IDRpze8y.js';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
+
+/**
+ * Foundation HTTP client for talking to the Sifa AppView.
+ *
+ * Stateless. Consumers supply a {@link SifaApiConfig} per call (the React
+ * hooks read it from context; non-React consumers pass it explicitly). No
+ * singletons, no module-level state.
+ */
+/** Configuration passed to every fetcher. */
+interface SifaApiConfig {
+    /** Base URL of the sifa-api AppView, e.g. `https://api.sifa.id`. No trailing slash. */
+    baseUrl: string;
+    /**
+     * Optional fetch implementation. Defaults to {@link globalThis.fetch}.
+     * Lets Next.js consumers pass their cache-enhanced fetch; node/Expo
+     * consumers can leave this unset.
+     */
+    fetch?: typeof fetch;
+}
+/** Options accepted by {@link apiFetch}. */
+interface ApiFetchOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** Request body. Serialized to JSON automatically. */
+    body?: unknown;
+    /** AbortSignal. Defaults to `AbortSignal.timeout(timeoutMs)` if `timeoutMs` is set. */
+    signal?: AbortSignal;
+    /** Per-call timeout in milliseconds. Default: 10_000. Ignored if `signal` is provided. */
+    timeoutMs?: number;
+    /** Retry on HTTP 429 up to 3 times with the server's `Retry-After` delay (capped at 3s). */
+    retryOn429?: boolean;
+    /** Additional headers. `Content-Type: application/json` is set automatically when `body` is present. */
+    headers?: Record<string, string>;
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+    /**
+     * Next.js-specific cache hints. Ignored on non-Next runtimes. Passed
+     * through transparently as part of {@link RequestInit}.
+     */
+    next?: {
+        revalidate?: number | false;
+        tags?: string[];
+    };
+}
+/** Error thrown by {@link apiFetch} on non-2xx responses. */
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/**
+ * Generic fetcher used by all SDK query and mutation functions.
+ *
+ * Returns parsed JSON typed as `T`. Throws {@link ApiError} on non-2xx
+ * responses. Use {@link apiFetchOrNull} when 404 should resolve to `null`
+ * instead.
+ */
+declare function apiFetch<T = unknown>(config: SifaApiConfig, path: string, options?: ApiFetchOptions): Promise<T>;
+/**
+ * Variant of {@link apiFetch} that resolves to `null` on HTTP 404 instead
+ * of throwing. Useful for "fetch by handle" reads where missing is
+ * expected (e.g. unknown profile).
+ */
+declare function apiFetchOrNull<T>(config: SifaApiConfig, path: string, options?: ApiFetchOptions): Promise<T | null>;
+
+interface SifaProviderProps {
+    config: SifaApiConfig;
+    children: ReactNode;
+}
+/**
+ * Provides the {@link SifaApiConfig} that hooks under it can read via
+ * {@link useSifaConfig}. Wrap the React tree once; hooks consume it.
+ *
+ * @example
+ * ```tsx
+ * <QueryClientProvider client={queryClient}>
+ *   <SifaProvider config={{ baseUrl: process.env.NEXT_PUBLIC_API_URL! }}>
+ *     <App />
+ *   </SifaProvider>
+ * </QueryClientProvider>
+ * ```
+ */
+declare function SifaProvider({ config, children }: SifaProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Read the SDK's {@link SifaApiConfig} from context. Throws if no
+ * {@link SifaProvider} is mounted above.
+ */
+declare function useSifaConfig(): SifaApiConfig;
+
+/**
+ * Read the aggregated profile for a handle or DID.
+ *
+ * Returns `null` when the AppView has no profile for the given identifier
+ * (HTTP 404). Throws {@link ApiError} on other non-2xx responses.
+ *
+ * Server-callable (Next.js RSC) and client-callable (Expo, browser).
+ */
+declare function fetchProfile(config: SifaApiConfig, handleOrDid: string, options?: ApiFetchOptions): Promise<Profile | null>;
+
+/** Result returned by record-write mutations (create / update / delete). */
+interface WriteResult {
+    success: boolean;
+    error?: string;
+    pdsHost?: string;
+}
+/** Result returned by create mutations. Includes the newly created `rkey`. */
+interface CreateResult extends WriteResult {
+    rkey?: string;
+}
+/**
+ * Create a new `id.sifa.profile.position` record on the authenticated
+ * user's PDS. The AppView signs and writes via the user's OAuth session.
+ *
+ * `data` should be a lexicon-shaped position record (without `createdAt`
+ * or `rkey`; the AppView fills both). Validate with
+ * `ProfilePositionRecordSchema.omit({ createdAt: true })` before calling
+ * if you want client-side guarantees.
+ */
+declare function createPosition(config: SifaApiConfig, data: Record<string, unknown>, options?: ApiFetchOptions): Promise<CreateResult>;
+
+/**
+ * React hook for creating a new position record. On success, invalidates
+ * the owner's profile cache so the new position is reflected on the next
+ * read.
+ *
+ * The owner DID is required so the mutation can target the correct
+ * profile cache entry for invalidation.
+ */
+declare function useCreatePosition(ownerDid: string, options?: Omit<UseMutationOptions<CreateResult, Error, Record<string, unknown>>, 'mutationFn'>): _tanstack_react_query.UseMutationResult<CreateResult, Error, Record<string, unknown>, unknown>;
+
+/**
+ * Query key factory for TanStack Query.
+ *
+ * Keys are read-only tuples; the hierarchy matches the SDK's fetcher
+ * grouping. Use these instead of inline arrays so consumers can target
+ * `queryClient.invalidateQueries({ queryKey: keys.profile.all() })` and
+ * similar patterns without typos.
+ *
+ * Convention: every leaf key starts with the namespace ('sifa') so
+ * consumers can invalidate everything Sifa-related in one call.
+ */
+declare const sifaQueryKeys: {
+    readonly all: () => readonly ["sifa"];
+    readonly profile: {
+        readonly all: () => readonly ["sifa", "profile"];
+        readonly byHandle: (handleOrDid: string) => readonly ["sifa", "profile", string];
+    };
+    readonly position: {
+        readonly all: () => readonly ["sifa", "position"];
+        readonly byOwner: (did: string) => readonly ["sifa", "position", "by-owner", string];
+    };
+};
+type SifaQueryKey = ReturnType<typeof sifaQueryKeys.all> | ReturnType<typeof sifaQueryKeys.profile.all> | ReturnType<typeof sifaQueryKeys.profile.byHandle> | ReturnType<typeof sifaQueryKeys.position.all> | ReturnType<typeof sifaQueryKeys.position.byOwner>;
+
+/**
+ * React hook that reads an aggregated profile by handle or DID via
+ * TanStack Query. Returns `null` data when the profile does not exist.
+ *
+ * Pass `{ enabled: false }` (or an empty `handleOrDid`) to defer the
+ * fetch.
+ */
+declare function useProfile(handleOrDid: string | undefined | null, options?: Omit<UseQueryOptions<Profile | null, Error, Profile | null, ReturnType<typeof sifaQueryKeys.profile.byHandle>>, 'queryKey' | 'queryFn'>): _tanstack_react_query.UseQueryResult<Profile | null, Error>;
+
+export { ApiError, type ApiFetchOptions, type CreateResult, type SifaApiConfig, SifaProvider, type SifaProviderProps, type SifaQueryKey, type WriteResult, apiFetch, apiFetchOrNull, createPosition, fetchProfile, sifaQueryKeys, useCreatePosition, useProfile, useSifaConfig };