@seedgrid/fe-core 2026.4.18 → 2026.4.20

package/dist/http/api-client.d.ts

@@ -0,0 +1,50 @@
+import { type ExceptionContext } from "./api-exception-handler";
+type Primitive = boolean | number | string;
+type QueryValue = Primitive | null | undefined;
+type QueryParams = Record<string, QueryValue>;
+type NextFetchOptions = {
+    revalidate?: false | number;
+    tags?: string[];
+};
+export type ApiParseMode = "json" | "response" | "text";
+export type ApiRetryOptions = {
+    attempts?: number;
+    baseDelayMs?: number;
+    retryOn?: number[];
+};
+export type ApiRequestOptions = Omit<RequestInit, "body" | "headers"> & {
+    body?: BodyInit | Record<string, unknown> | null;
+    headers?: HeadersInit;
+    next?: NextFetchOptions;
+    parseAs?: ApiParseMode;
+    query?: QueryParams;
+    requireAuth?: boolean;
+    retry?: boolean | ApiRetryOptions;
+    captureExceptions?: boolean;
+};
+export type ApiClientConfig = {
+    baseUrl: string;
+    defaultHeaders?: HeadersInit;
+    defaultCache?: RequestCache;
+    defaultNext?: NextFetchOptions;
+    getAccessToken?: () => Promise<string | null>;
+    refreshAccessToken?: () => Promise<string | null>;
+    onAuthFailure?: (context: ExceptionContext) => void | Promise<void>;
+    onException?: (error: Error, context: ExceptionContext) => void | Promise<void>;
+};
+export declare class ApiClientError extends Error {
+    readonly responseBody: unknown;
+    readonly status: number;
+    constructor(message: string, status: number, responseBody?: unknown);
+}
+export declare function createApiClient(config: ApiClientConfig): {
+    request: <T = unknown>(path: string, options?: ApiRequestOptions) => Promise<T>;
+    get: <T = unknown>(path: string, options?: ApiRequestOptions) => Promise<T>;
+    post: <T = unknown>(path: string, options?: ApiRequestOptions) => Promise<T>;
+    put: <T = unknown>(path: string, options?: ApiRequestOptions) => Promise<T>;
+    patch: <T = unknown>(path: string, options?: ApiRequestOptions) => Promise<T>;
+    delete: <T = unknown>(path: string, options?: ApiRequestOptions) => Promise<T>;
+};
+export declare function formatCurlCommand(url: string, init: RequestInit): string;
+export {};
+//# sourceMappingURL=api-client.d.ts.map

package/dist/http/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/http/api-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,KAAK,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,KAAK,UAAU,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,CAAC;AAE/C,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE9C,KAAK,gBAAgB,GAAG;IACtB,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IACtE,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjD,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,WAAW,CAAC;IAC7B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClD,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,WAAW,CAAC,EAAE,CACZ,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,gBAAgB,KACtB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B,CAAC;AAEF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO;CAMpE;AAID,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe;cAK9B,CAAC,kBAChB,MAAM,YACH,iBAAiB,KACzB,OAAO,CAAC,CAAC,CAAC;UAgIL,CAAC,kBAAkB,MAAM,YAAW,iBAAiB;WAKpD,CAAC,kBAAkB,MAAM,YAAW,iBAAiB;UAKtD,CAAC,kBAAkB,MAAM,YAAW,iBAAiB;YAKnD,CAAC,kBAAkB,MAAM,YAAW,iBAAiB;aAKpD,CAAC,kBAAkB,MAAM,YAAW,iBAAiB;EAMjE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,UAmB/D"}

package/dist/http/api-client.js

@@ -0,0 +1,281 @@
+// seedgrid:managed
+import { captureException, runGuarded, suppressException, } from "./api-exception-handler";
+export class ApiClientError extends Error {
+    responseBody;
+    status;
+    constructor(message, status, responseBody) {
+        super(message);
+        this.name = "ApiClientError";
+        this.status = status;
+        this.responseBody = responseBody;
+    }
+}
+const DEFAULT_RETRY_STATUSES = [429, 502, 503, 504];
+export function createApiClient(config) {
+    function shouldCapture(options) {
+        return options.captureExceptions !== false;
+    }
+    async function request(path, options = {}) {
+        return runGuarded(async () => {
+            const retry = resolveRetryOptions(options.retry);
+            let refreshedToken = false;
+            let latestAccessToken;
+            const requiresAuth = options.requireAuth ?? true;
+            for (let attempt = 0; attempt <= retry.attempts; attempt += 1) {
+                try {
+                    latestAccessToken ??= await readAccessToken(config.getAccessToken, requiresAuth);
+                    const url = buildUrl(config.baseUrl, path, options.query);
+                    const requestInit = buildRequestInit(config, options, latestAccessToken);
+                    if (process.env.NODE_ENV !== "production") {
+                        console.debug(formatCurlCommand(url, requestInit));
+                    }
+                    const response = await fetch(url, requestInit);
+                    if (response.status === 401 &&
+                        !refreshedToken &&
+                        typeof config.refreshAccessToken === "function" &&
+                        requiresAuth) {
+                        refreshedToken = true;
+                        latestAccessToken = await config.refreshAccessToken();
+                        if (!latestAccessToken) {
+                            const responseBody = await readResponseBody(response);
+                            const error = new ApiClientError(`API request failed with status ${response.status}`, response.status, responseBody);
+                            const context = {
+                                area: "api",
+                                source: path,
+                                retryable: false,
+                                status: response.status,
+                            };
+                            await config.onAuthFailure?.(context);
+                            if (shouldCapture(options)) {
+                                await config.onException?.(error, context);
+                                await captureException(error, context);
+                            }
+                            else {
+                                suppressException(error);
+                            }
+                            throw error;
+                        }
+                        attempt -= 1;
+                        continue;
+                    }
+                    if (response.ok) {
+                        return parseResponse(response, options.parseAs ?? "json");
+                    }
+                    const responseBody = await readResponseBody(response);
+                    const error = new ApiClientError(`API request failed with status ${response.status}`, response.status, responseBody);
+                    if (shouldRetryStatus(response.status, retry, attempt)) {
+                        await sleep(backoffDelay(retry.baseDelayMs, attempt));
+                        continue;
+                    }
+                    const context = {
+                        area: "api",
+                        source: path,
+                        retryable: false,
+                        status: response.status,
+                    };
+                    if (response.status === 401 && requiresAuth) {
+                        await config.onAuthFailure?.(context);
+                    }
+                    if (shouldCapture(options)) {
+                        await config.onException?.(error, context);
+                        await captureException(error, context);
+                    }
+                    else {
+                        suppressException(error);
+                    }
+                    throw error;
+                }
+                catch (error) {
+                    if (shouldRetryNetworkFailure(error, retry, attempt)) {
+                        await sleep(backoffDelay(retry.baseDelayMs, attempt));
+                        continue;
+                    }
+                    const normalized = error instanceof Error ? error : new Error(String(error));
+                    const context = {
+                        area: "api",
+                        source: path,
+                        retryable: isNetworkError(error),
+                    };
+                    if (shouldCapture(options)) {
+                        await config.onException?.(normalized, context);
+                        await captureException(normalized, context);
+                    }
+                    else {
+                        suppressException(normalized);
+                    }
+                    throw normalized;
+                }
+            }
+            throw new Error("API request exhausted retry attempts");
+        }, {
+            area: "api",
+            source: path,
+        });
+    }
+    return {
+        request,
+        get: (path, options = {}) => request(path, {
+            ...options,
+            method: "GET",
+        }),
+        post: (path, options = {}) => request(path, {
+            ...options,
+            method: "POST",
+        }),
+        put: (path, options = {}) => request(path, {
+            ...options,
+            method: "PUT",
+        }),
+        patch: (path, options = {}) => request(path, {
+            ...options,
+            method: "PATCH",
+        }),
+        delete: (path, options = {}) => request(path, {
+            ...options,
+            method: "DELETE",
+        }),
+    };
+}
+export function formatCurlCommand(url, init) {
+    const method = (init.method ?? "GET").toUpperCase();
+    const sanitizedUrl = escapeSingleQuotes(url);
+    const headers = new Headers(init.headers ?? {});
+    const headerArgs = Array.from(headers.entries())
+        .map(([key, value]) => `-H "${key}: ${value}"`)
+        .join(" ");
+    const bodyArg = buildBodyArg(init.body);
+    const parts = [`curl -X ${method} '${sanitizedUrl}'`];
+    if (headerArgs) {
+        parts.push(headerArgs);
+    }
+    if (bodyArg) {
+        parts.push(bodyArg);
+    }
+    return parts.join(" ");
+}
+function buildBodyArg(body) {
+    if (typeof body === "string") {
+        return `--data-raw '${escapeSingleQuotes(body)}'`;
+    }
+    if (body instanceof URLSearchParams) {
+        return `--data-raw '${escapeSingleQuotes(body.toString())}'`;
+    }
+    return "";
+}
+function escapeSingleQuotes(value) {
+    return value.replace(/'/g, "'\\''");
+}
+async function parseResponse(response, parseAs) {
+    if (parseAs === "response") {
+        return response;
+    }
+    if (parseAs === "text") {
+        return (await response.text());
+    }
+    if (response.status === 204) {
+        return null;
+    }
+    return (await response.json());
+}
+function buildRequestInit(config, options, accessToken) {
+    const headers = new Headers(config.defaultHeaders ?? {});
+    mergeHeaders(headers, options.headers);
+    const body = normalizeBody(options.body, headers);
+    if (accessToken) {
+        headers.set("Authorization", `Bearer ${accessToken}`);
+    }
+    return {
+        ...options,
+        body,
+        cache: options.cache ?? config.defaultCache,
+        headers,
+        next: options.next ?? config.defaultNext,
+    };
+}
+function normalizeBody(body, headers) {
+    if (body == null) {
+        return body;
+    }
+    if (typeof body === "string" ||
+        body instanceof Blob ||
+        body instanceof FormData ||
+        body instanceof URLSearchParams ||
+        body instanceof ArrayBuffer) {
+        return body;
+    }
+    headers.set("Content-Type", "application/json");
+    return JSON.stringify(body);
+}
+function mergeHeaders(target, source) {
+    if (!source) {
+        return;
+    }
+    new Headers(source).forEach((value, key) => {
+        target.set(key, value);
+    });
+}
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(path, baseUrl);
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value == null) {
+            continue;
+        }
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+function resolveRetryOptions(retry) {
+    if (retry === false || retry == null) {
+        return {
+            attempts: 0,
+            baseDelayMs: 250,
+            retryOn: DEFAULT_RETRY_STATUSES,
+        };
+    }
+    if (retry === true) {
+        return {
+            attempts: 2,
+            baseDelayMs: 250,
+            retryOn: DEFAULT_RETRY_STATUSES,
+        };
+    }
+    return {
+        attempts: retry.attempts ?? 2,
+        baseDelayMs: retry.baseDelayMs ?? 250,
+        retryOn: retry.retryOn ?? DEFAULT_RETRY_STATUSES,
+    };
+}
+function shouldRetryStatus(status, retry, attempt) {
+    return attempt < retry.attempts && retry.retryOn.includes(status);
+}
+function shouldRetryNetworkFailure(error, retry, attempt) {
+    return attempt < retry.attempts && isNetworkError(error);
+}
+function isNetworkError(error) {
+    return error instanceof TypeError;
+}
+function backoffDelay(baseDelayMs, attempt) {
+    return baseDelayMs * (attempt + 1);
+}
+async function sleep(ms) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function readAccessToken(getAccessToken, requireAuth) {
+    if (!requireAuth || typeof getAccessToken !== "function") {
+        return null;
+    }
+    return getAccessToken();
+}
+async function readResponseBody(response) {
+    const contentType = response.headers.get("Content-Type") ?? "";
+    if (isJsonContentType(contentType)) {
+        return response.json();
+    }
+    return response.text();
+}
+function isJsonContentType(contentType) {
+    const normalized = contentType.trim().toLowerCase();
+    return normalized.includes("/json") || normalized.includes("+json");
+}

package/dist/http/api-client.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=api-client.meta.d.ts.map

package/dist/http/api-client.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.meta.d.ts","sourceRoot":"","sources":["../../src/http/api-client.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QAyEpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAyBrB,CAAC"}

package/dist/http/api-client.meta.js

@@ -0,0 +1,99 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "factory.api-client",
+    package: "@seedgrid/fe-core",
+    exportName: "createApiClient",
+    slug: "create-api-client",
+    displayName: "API Client Factory",
+    category: "factory",
+    subcategory: "http",
+    description: "Factory function that creates a fetch-based API client with auth token injection, retry policies, response parsing, cURL debug output, and typed request helpers.",
+    tags: ["api", "http", "fetch", "auth", "retry", "json"],
+    capabilities: ["get", "post", "put", "patch", "delete", "refresh-token", "response-parse", "query-params"],
+    fieldSemantics: ["api", "request", "authentication", "retry", "error-handling"],
+    props: [
+        {
+            name: "baseUrl",
+            type: "string",
+            required: true,
+            description: "Base URL used to resolve relative API paths.",
+            semanticRole: "data",
+        },
+        {
+            name: "getAccessToken",
+            type: "() => Promise<string | null>",
+            required: false,
+            description: "Async callback used to read the current access token before authenticated requests.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "refreshAccessToken",
+            type: "() => Promise<string | null>",
+            required: false,
+            description: "Async callback used after a 401 to obtain a fresh access token and retry once.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "defaultHeaders",
+            type: "HeadersInit",
+            required: false,
+            description: "Headers merged into every request before per-request overrides.",
+            semanticRole: "data",
+        },
+        {
+            name: "defaultCache",
+            type: "RequestCache",
+            required: false,
+            description: "Default fetch cache mode used when a request does not override cache.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "defaultNext",
+            type: "{ revalidate?: false | number; tags?: string[] }",
+            required: false,
+            description: "Next.js fetch options reused across requests.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "onAuthFailure",
+            type: "(context: ExceptionContext) => void | Promise<void>",
+            required: false,
+            description: "Optional callback fired when an authenticated request still fails with 401.",
+            semanticRole: "event",
+        },
+        {
+            name: "onException",
+            type: "(error: Error, context: ExceptionContext) => void | Promise<void>",
+            required: false,
+            description: "Optional callback invoked before captured API exceptions are rethrown.",
+            semanticRole: "event",
+        },
+    ],
+    states: ["ready", "requesting", "retrying", "failed"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Server or client HTTP access where auth tokens, retries, and typed JSON parsing should be standardized.",
+        "Application modules that need consistent GET/POST/PUT/PATCH/DELETE helpers instead of ad hoc fetch calls.",
+        "Next.js integrations that need cache/next options to flow through a shared API layer.",
+    ],
+    avoidUseCases: [
+        "Very small one-off fetch calls where a dedicated client adds no value.",
+        "Streaming or multipart-heavy workflows that need low-level fetch control.",
+    ],
+    synonyms: ["api client", "fetch wrapper", "http client", "authenticated fetch", "request factory"],
+    relatedEntityFields: ["api", "request", "auth", "token", "retry", "http"],
+    compositionHints: [
+        "Pair createApiClient with captureException or module-level error translation when surfacing server errors to the UI.",
+        "Use requireAuth: false for public endpoints; leave it enabled by default for private endpoints.",
+        "Use parseAs: 'response' when the caller needs raw headers or binary body handling.",
+    ],
+    rankingSignals: {
+        freeText: 0.35,
+        structuredChoice: 0.3,
+        date: 0,
+        number: 0.05,
+        denseLayout: 0.1,
+    },
+};

package/dist/http/api-exception-handler.d.ts

@@ -0,0 +1,15 @@
+export type ExceptionArea = "api" | "client" | "server";
+export type ExceptionContext = {
+    area?: ExceptionArea;
+    source?: string;
+    status?: number;
+    retryable?: boolean;
+    metadata?: Record<string, unknown>;
+};
+export type ExceptionReporter = (error: Error, context: ExceptionContext) => void | Promise<void>;
+export declare function suppressException(error: Error): void;
+export declare function registerExceptionReporter(reporter: ExceptionReporter): () => void;
+export declare function normalizeError(error: unknown): Error;
+export declare function captureException(error: unknown, context?: ExceptionContext): Promise<Error>;
+export declare function runGuarded<T>(action: () => Promise<T> | T, context?: ExceptionContext): Promise<T>;
+//# sourceMappingURL=api-exception-handler.d.ts.map

package/dist/http/api-exception-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-exception-handler.d.ts","sourceRoot":"","sources":["../../src/http/api-exception-handler.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,gBAAgB,KACtB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAK1B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,QAE7C;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,iBAAiB,cAMpE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAUpD;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gBAAqB,kBAqB/B;AAED,wBAAsB,UAAU,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC5B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/http/api-exception-handler.js

@@ -0,0 +1,53 @@
+// seedgrid:managed
+const reporters = new Set();
+const CAPTURED_ERROR_SYMBOL = Symbol.for("seedgrid.captured_exception");
+export function suppressException(error) {
+    markAsCaptured(error);
+}
+export function registerExceptionReporter(reporter) {
+    reporters.add(reporter);
+    return () => {
+        reporters.delete(reporter);
+    };
+}
+export function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === "string") {
+        return new Error(error);
+    }
+    return new Error("Unknown application error");
+}
+export async function captureException(error, context = {}) {
+    const normalized = normalizeError(error);
+    if (wasCaptured(normalized)) {
+        return normalized;
+    }
+    markAsCaptured(normalized);
+    console.error("[seedgrid]", normalized, context);
+    for (const reporter of reporters) {
+        try {
+            await reporter(normalized, context);
+        }
+        catch (reporterError) {
+            console.error("[seedgrid] reporter failed", reporterError);
+        }
+    }
+    return normalized;
+}
+export async function runGuarded(action, context = {}) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        await captureException(error, context);
+        throw error;
+    }
+}
+function wasCaptured(error) {
+    return Boolean(error[CAPTURED_ERROR_SYMBOL]);
+}
+function markAsCaptured(error) {
+    error[CAPTURED_ERROR_SYMBOL] = true;
+}

package/dist/http/api-exception-handler.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=api-exception-handler.meta.d.ts.map

package/dist/http/api-exception-handler.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-exception-handler.meta.d.ts","sourceRoot":"","sources":["../../src/http/api-exception-handler.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QA+BpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAyBrB,CAAC"}