@graph8/sdk 0.308.1 → 0.357.0

package/blocks/_foundation/hooks/use-g8-query.ts

@@ -0,0 +1,87 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseG8QueryOptions<T> {
+  /** Set false to hold the request (for example until a required id is known). */
+  enabled?: boolean;
+  /** Shown until the first response lands. */
+  initialData?: T;
+}
+
+export interface UseG8QueryResult<T> {
+  data: T | undefined;
+  error: unknown;
+  /** True while a request is in flight, including a refetch (stale `data` stays visible). */
+  loading: boolean;
+  /** Re-run the request now. Resolves with the data, or undefined if it failed or was superseded. */
+  refetch: () => Promise<T | undefined>;
+}
+
+/**
+ * Load data when the component mounts and whenever `deps` change.
+ *
+ * Out-of-order guard: only the LATEST request may write state. A slow response
+ * for an old filter can never overwrite the fresh one, and the older request
+ * is aborted through the `signal` passed to `fetcher`.
+ *
+ *   const { data, loading, error, refetch } = useG8Query(
+ *     (signal) => g8Get("/contacts", { limit: 50 }, { signal }),
+ *     [],
+ *   );
+ */
+export function useG8Query<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly unknown[],
+  options: UseG8QueryOptions<T> = {},
+): UseG8QueryResult<T> {
+  const enabled = options.enabled ?? true;
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+  const latest = useRef(0);
+  const controller = useRef<AbortController | null>(null);
+  const mounted = useRef(true);
+  const [data, setData] = useState<T | undefined>(options.initialData);
+  const [error, setError] = useState<unknown>(undefined);
+  const [loading, setLoading] = useState<boolean>(enabled);
+
+  const run = useCallback(async (): Promise<T | undefined> => {
+    const id = ++latest.current;
+    controller.current?.abort();
+    const ctl = new AbortController();
+    controller.current = ctl;
+    setLoading(true);
+    try {
+      const result = await fetcherRef.current(ctl.signal);
+      if (id !== latest.current || !mounted.current) return undefined;
+      setData(result);
+      setError(undefined);
+      setLoading(false);
+      return result;
+    } catch (err) {
+      if (id !== latest.current || !mounted.current) return undefined;
+      setError(err);
+      setLoading(false);
+      return undefined;
+    }
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    if (!enabled) {
+      latest.current++;
+      controller.current?.abort();
+      setLoading(false);
+      return;
+    }
+    void run();
+    return () => {
+      mounted.current = false;
+      latest.current++;
+      controller.current?.abort();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, run, ...deps]);
+
+  return { data, error, loading, refetch: run };
+}

package/blocks/_foundation/hooks/use-job-poll.ts

@@ -0,0 +1,130 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseJobPollOptions<TStatus> {
+  /** Return true when the job will not change any more (done, failed, cancelled). */
+  isTerminal: (status: TStatus) => boolean;
+  /** Start polling on mount. Default true. Set false and call `start()` yourself. */
+  enabled?: boolean;
+  /** First delay between polls. Default 1500 ms. */
+  intervalMs?: number;
+  /** Delay grows by `backoff` each poll up to this ceiling. Default 15000 ms. */
+  maxIntervalMs?: number;
+  /** Growth factor per poll. Default 1.5. */
+  backoff?: number;
+  /** Give up after this many polls. Default 200. */
+  maxAttempts?: number;
+  /** Fetch failures in a row tolerated before stopping. Default 3. */
+  maxConsecutiveErrors?: number;
+  onDone?: (status: TStatus) => void;
+}
+
+export interface UseJobPollResult<TStatus> {
+  status: TStatus | undefined;
+  error: unknown;
+  polling: boolean;
+  /** A terminal status was reached. */
+  done: boolean;
+  /** Polls made so far. */
+  attempts: number;
+  start: () => void;
+  stop: () => void;
+}
+
+function isClientError(err: unknown): boolean {
+  const status = (err as { status?: number } | null)?.status;
+  return typeof status === "number" && status >= 400 && status < 500 && status !== 429;
+}
+
+/**
+ * Poll a job-status fetcher until a terminal state. The API has no streams or
+ * websockets, so enrichment jobs, bulk imports and exports are all followed this
+ * way. The delay grows by `backoff` each poll, so a long job stays cheap.
+ *
+ * A 4xx (other than 429) stops immediately; transient failures are retried up
+ * to `maxConsecutiveErrors` times in a row.
+ *
+ *   const job = useJobPoll((signal) => g8Get<Job>(`/enrichment/jobs/${id}`, {}, { signal }).then((r) => r.data),
+ *     { isTerminal: (j) => j.status === "completed" || j.status === "failed" });
+ */
+export function useJobPoll<TStatus>(
+  fetchStatus: (signal: AbortSignal) => Promise<TStatus>,
+  options: UseJobPollOptions<TStatus>,
+): UseJobPollResult<TStatus> {
+  const fetchRef = useRef(fetchStatus);
+  fetchRef.current = fetchStatus;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const run = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const controller = useRef<AbortController | null>(null);
+  const [status, setStatus] = useState<TStatus | undefined>(undefined);
+  const [error, setError] = useState<unknown>(undefined);
+  const [polling, setPolling] = useState(false);
+  const [done, setDone] = useState(false);
+  const [attempts, setAttempts] = useState(0);
+
+  const stop = useCallback(() => {
+    run.current++;
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    controller.current?.abort();
+    setPolling(false);
+  }, []);
+
+  const start = useCallback(() => {
+    stop();
+    const me = ++run.current;
+    setDone(false);
+    setError(undefined);
+    setPolling(true);
+    let attempt = 0;
+    let failures = 0;
+
+    const finish = (): void => {
+      if (me === run.current) setPolling(false);
+    };
+    const schedule = (): void => {
+      const { intervalMs = 1500, maxIntervalMs = 15000, backoff = 1.5 } = optionsRef.current;
+      const delay = Math.min(maxIntervalMs, intervalMs * Math.pow(backoff, Math.max(0, attempt - 1)));
+      timer.current = setTimeout(() => void tick(), delay);
+    };
+    const tick = async (): Promise<void> => {
+      const ctl = new AbortController();
+      controller.current = ctl;
+      attempt++;
+      try {
+        const next = await fetchRef.current(ctl.signal);
+        if (me !== run.current) return;
+        failures = 0;
+        setError(undefined);
+        setStatus(next);
+        setAttempts(attempt);
+        if (optionsRef.current.isTerminal(next)) {
+          setDone(true);
+          finish();
+          optionsRef.current.onDone?.(next);
+          return;
+        }
+      } catch (err) {
+        if (me !== run.current) return;
+        failures++;
+        setAttempts(attempt);
+        setError(err);
+        if (isClientError(err) || failures > (optionsRef.current.maxConsecutiveErrors ?? 3)) return finish();
+      }
+      if (attempt >= (optionsRef.current.maxAttempts ?? 200)) return finish();
+      schedule();
+    };
+    void tick();
+  }, [stop]);
+
+  const enabled = options.enabled ?? true;
+  useEffect(() => {
+    if (enabled) start();
+    return stop;
+  }, [enabled, start, stop]);
+
+  return { status, error, polling, done, attempts, start, stop };
+}

package/blocks/_foundation/hooks/use-paginated.ts

@@ -0,0 +1,105 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { PaginatedResponse } from "@graph8/sdk";
+
+export interface UsePaginatedOptions {
+  enabled?: boolean;
+}
+
+export interface UsePaginatedResult<T> {
+  items: T[];
+  /** True while the FIRST page loads (or reloads after `deps` change). */
+  loading: boolean;
+  /** True while a following page loads. */
+  loadingMore: boolean;
+  error: unknown;
+  /** The last response carried a `pagination.next_cursor`. */
+  hasMore: boolean;
+  loadMore: () => Promise<void>;
+  /** Start over from the first page. */
+  reload: () => Promise<void>;
+}
+
+/**
+ * Cursor pagination over the API envelope: `{ data: T[], pagination: { next_cursor } }`.
+ * Pages append to `items`; changing `deps` (a filter, a search box) starts over.
+ * Stale responses from a previous filter are discarded.
+ *
+ *   const { items, hasMore, loadMore } = usePaginated(
+ *     (cursor, signal) => g8Get<Contact[]>("/contacts", { limit: 50, cursor }, { signal }),
+ *     [filter],
+ *   );
+ */
+export function usePaginated<T>(
+  fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>,
+  deps: readonly unknown[],
+  options: UsePaginatedOptions = {},
+): UsePaginatedResult<T> {
+  const enabled = options.enabled ?? true;
+  const fetchRef = useRef(fetchPage);
+  fetchRef.current = fetchPage;
+  const generation = useRef(0);
+  const cursorRef = useRef<string | undefined>(undefined);
+  const busy = useRef(false);
+  const controller = useRef<AbortController | null>(null);
+  const [items, setItems] = useState<T[]>([]);
+  const [loading, setLoading] = useState(enabled);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState<unknown>(undefined);
+  const [hasMore, setHasMore] = useState(false);
+
+  const load = useCallback(async (reset: boolean): Promise<void> => {
+    if (!reset && (busy.current || !cursorRef.current)) return;
+    if (reset) {
+      generation.current++;
+      controller.current?.abort();
+      cursorRef.current = undefined;
+    }
+    const gen = generation.current;
+    const ctl = new AbortController();
+    controller.current = ctl;
+    busy.current = true;
+    if (reset) setLoading(true);
+    else setLoadingMore(true);
+    try {
+      const page = await fetchRef.current(reset ? undefined : cursorRef.current, ctl.signal);
+      if (gen !== generation.current) return;
+      const next = page.pagination?.next_cursor ?? undefined;
+      cursorRef.current = next;
+      setItems((prev) => (reset ? [...(page.data ?? [])] : [...prev, ...(page.data ?? [])]));
+      setHasMore(Boolean(next));
+      setError(undefined);
+    } catch (err) {
+      if (gen !== generation.current) return;
+      setError(err);
+    } finally {
+      if (gen === generation.current) {
+        busy.current = false;
+        setLoading(false);
+        setLoadingMore(false);
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) {
+      generation.current++;
+      controller.current?.abort();
+      busy.current = false;
+      setLoading(false);
+      return;
+    }
+    void load(true);
+    return () => {
+      generation.current++;
+      controller.current?.abort();
+      busy.current = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, load, ...deps]);
+
+  const loadMore = useCallback(() => load(false), [load]);
+  const reload = useCallback(() => load(true), [load]);
+  return { items, loading, loadingMore, error, hasMore, loadMore, reload };
+}

package/blocks/_foundation/lib/g8-client.ts

@@ -0,0 +1,128 @@
+"use client";
+
+/**
+ * Browser-side caller for graph8.
+ *
+ * It never holds an API key. Every call goes to YOUR app's own proxy route
+ * (`app/api/g8/[...path]/route.ts`, see ../server/route.ts), which adds the
+ * server-side key and forwards to the graph8 API. Paths are relative to
+ * `/api/v1`, exactly as the API reference writes them: `g8Get("/contacts")`.
+ *
+ * Success returns the API envelope unchanged (`{ data, pagination?, ... }`).
+ * Any failure throws `G8Error` from `@graph8/sdk`, the same class the server
+ * SDK throws, so `err.status`, `err.detail` and `err.requestId` mean the same
+ * thing in the browser.
+ */
+
+import { G8Error } from "@graph8/sdk";
+import type { PaginatedResponse } from "@graph8/sdk";
+
+/** The envelope every graph8 list/read call returns. */
+export type G8Envelope<T = unknown> = {
+  data: T;
+  pagination?: PaginatedResponse<unknown>["pagination"];
+} & Record<string, unknown>;
+
+export type G8QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+
+export interface G8CallOptions {
+  /** Query-string parameters. `null`/`undefined` are dropped; arrays repeat the key. */
+  query?: Record<string, G8QueryValue>;
+  /** JSON request body (objects are serialised; `FormData` is sent as-is). */
+  body?: unknown;
+  /** Reuse the same key when YOUR code may repeat a write (a double click, a retry). */
+  idempotencyKey?: string;
+  /** Agency keys only: the client org the call acts on. */
+  targetOrgId?: string;
+  signal?: AbortSignal;
+}
+
+export type G8Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** Where the proxy route is mounted. Change it in one place if your route lives elsewhere. */
+export const G8_PROXY_BASE = "/api/g8";
+
+/** @internal Swappable in tests. */
+export const transport = { fetch: (...args: Parameters<typeof fetch>) => globalThis.fetch(...args) };
+
+export function buildG8Url(path: string, query?: G8CallOptions["query"]): string {
+  const clean = path.replace(/^\/+/, "").replace(/^api\/v1\//, "");
+  const qs = new URLSearchParams();
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value == null) continue;
+    for (const item of Array.isArray(value) ? value : [value]) qs.append(key, String(item));
+  }
+  const suffix = qs.toString();
+  return `${G8_PROXY_BASE}/${clean}${suffix ? `?${suffix}` : ""}`;
+}
+
+async function toError(resp: Response): Promise<G8Error> {
+  let env: Record<string, unknown> = {};
+  try {
+    const text = await resp.text();
+    env = text ? (JSON.parse(text) as Record<string, unknown>) : {};
+  } catch {
+    env = {};
+  }
+  const message =
+    (typeof env.message === "string" && env.message) ||
+    (typeof env.error === "string" && env.error) ||
+    `Request failed with status ${resp.status}`;
+  return new G8Error({
+    message,
+    status: resp.status,
+    type: (typeof env.type === "string" && env.type) || (typeof env.error === "string" && env.error) || "api_error",
+    code: typeof env.code === "string" ? env.code : String(resp.status),
+    requestId: (typeof env.request_id === "string" && env.request_id) || resp.headers.get("x-request-id") || undefined,
+    detail: env.detail,
+    retryable: resp.status === 429 || resp.status >= 500,
+  });
+}
+
+function buildInit(method: G8Method, options: G8CallOptions): RequestInit {
+  const headers: Record<string, string> = { Accept: "application/json" };
+  let body: BodyInit | undefined;
+  if (options.body instanceof FormData) {
+    body = options.body;
+  } else if (options.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(options.body);
+  }
+  if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+  if (options.targetOrgId) headers["X-Target-Org-Id"] = options.targetOrgId;
+  return { method, headers, body, signal: options.signal, credentials: "same-origin" };
+}
+
+/** Call any graph8 operation through the proxy. Throws `G8Error` on any failure. */
+export async function g8Call<T = unknown>(
+  method: G8Method,
+  path: string,
+  options: G8CallOptions = {},
+): Promise<G8Envelope<T>> {
+  let resp: Response;
+  try {
+    resp = await transport.fetch(buildG8Url(path, options.query), buildInit(method, options));
+  } catch (err) {
+    if ((err as Error)?.name === "AbortError") throw err;
+    throw new G8Error({
+      message: `Network error: ${(err as Error)?.message ?? "request failed"}`,
+      status: 0,
+      type: "network_error",
+      retryable: true,
+    });
+  }
+  if (!resp.ok) throw await toError(resp);
+  const text = await resp.text();
+  return (text ? JSON.parse(text) : { data: null }) as G8Envelope<T>;
+}
+
+export const g8Get = <T = unknown>(path: string, query?: G8CallOptions["query"], options: G8CallOptions = {}) =>
+  g8Call<T>("GET", path, { ...options, query });
+export const g8Post = <T = unknown>(path: string, body?: unknown, options: G8CallOptions = {}) =>
+  g8Call<T>("POST", path, { ...options, body });
+export const g8Put = <T = unknown>(path: string, body?: unknown, options: G8CallOptions = {}) =>
+  g8Call<T>("PUT", path, { ...options, body });
+export const g8Patch = <T = unknown>(path: string, body?: unknown, options: G8CallOptions = {}) =>
+  g8Call<T>("PATCH", path, { ...options, body });
+export const g8Delete = <T = unknown>(path: string, options: G8CallOptions = {}) =>
+  g8Call<T>("DELETE", path, options);

package/blocks/_foundation/recipes/verify-proxy-key.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Check the proxy's server key before shipping
+ * @when After setting G8_API_KEY for the proxy route. Run it once in a server script or a route handler:
+ * a wrong, expired or unscoped key fails here with a clear G8Error instead of as a 401 in every browser call.
+ */
+import { g8, G8Error } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function verifyProxyKey(): Promise<unknown> {
+  try {
+    const me = await g8.api.me.describeCurrentKey();
+    return me.data;
+  } catch (err) {
+    if (err instanceof G8Error) throw new Error(`G8_API_KEY rejected (${err.status}): ${JSON.stringify(err.detail)}`);
+    throw err;
+  }
+}