@singi-labs/sifa-sdk 0.5.0 → 0.6.0

package/dist/query/index.js

@@ -0,0 +1,150 @@
+import { createContext, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+import { useQueryClient, useMutation, useQuery } from '@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 = createContext(null);
+function SifaProvider({ config, children }) {
+  return /* @__PURE__ */ jsx(SifaConfigContext.Provider, { value: config, children });
+}
+function useSifaConfig() {
+  const ctx = 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 = useQueryClient();
+  return 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 useQuery({
+    queryKey: sifaQueryKeys.profile.byHandle(handleOrDid ?? ""),
+    queryFn: () => fetchProfile(config, handleOrDid ?? ""),
+    enabled: Boolean(handleOrDid) && (options?.enabled ?? true),
+    ...options
+  });
+}
+
+export { ApiError, SifaProvider, apiFetch, apiFetchOrNull, createPosition, fetchProfile, sifaQueryKeys, useCreatePosition, useProfile, useSifaConfig };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.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":[],"mappings":"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","file":"index.js","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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@singi-labs/sifa-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Sifa SDK — public client library for the Sifa AppView on AT Protocol. Shared by sifa-web and sifa-app.",
   "license": "MIT",
   "type": "module",
@@ -51,31 +51,59 @@
         "default": "./dist/schemas/index.cjs"
       }
     },
+    "./query": {
+      "import": {
+        "types": "./dist/query/index.d.ts",
+        "default": "./dist/query/index.js"
+      },
+      "require": {
+        "types": "./dist/query/index.d.cts",
+        "default": "./dist/query/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.100.0",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@changesets/cli": "2.31.0",
     "@commitlint/cli": "21.0.1",
     "@commitlint/config-conventional": "21.0.1",
+    "@tanstack/react-query": "5.100.10",
+    "@testing-library/react": "16.3.2",
+    "@types/react": "19.2.14",
     "@vitest/coverage-v8": "3.2.1",
     "eslint": "10.3.0",
     "husky": "9.1.7",
+    "jsdom": "27.0.0",
     "prettier": "3.8.3",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
     "typescript-eslint": "8.59.3",
     "vitest": "3.2.1"
   },
-  "engines": {
-    "node": ">=22"
-  },
-  "dependencies": {
-    "zod": "4.4.3"
-  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",