@x12i/api-hub-core 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @x12i/api-hub-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Capability contract, error model, and catalog types for the x12i API hub
+
+ESM package for Node.js 24 or newer. Import the public name:
+
+```js
+import * as core from '@x12i/api-hub-core';
+```
+
+The whole set is also available from [`@x12i/api-hub`](https://www.npmjs.com/package/@x12i/api-hub).

package/dist/capability.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import type { Requirement } from './connections.js';
+import type { Ctx } from './context.js';
+import type { ProxySpec } from './upstream-types.js';
+import type { Sourcing } from './registry-types.js';
+export type CapabilityMode = 'sync' | 'job';
+export interface CapabilityLimits {
+    timeoutMs: number;
+    maxInputBytes: number;
+}
+/** A hub that can serve this capability. `failover` is true when the runtime may call it with the same input. */
+export interface CatalogUpstream {
+    hub: string;
+    api: string | null;
+    priceUsd: number | null;
+    failover: boolean;
+}
+export interface CapabilityDefinition<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
+    /** Exactly the workbook's Capability value. */
+    slug: string;
+    /** One sentence, in our own words. */
+    summary: string;
+    input: I;
+    output: O;
+    sourcing: Sourcing;
+    mode: CapabilityMode;
+    limits: CapabilityLimits;
+    /** x12i packages actually used, after verification. */
+    reuse: string[];
+    /** Engineer-days actually spent, for the next sizing round. */
+    actualDays?: number;
+    /** Operator-configured services the handler needs; drives `connected` and `missing` in the catalog. */
+    requires?: Requirement[];
+    /** Example input used by docs and the contract check. */
+    examples?: z.input<I>[];
+    /** Hubs that can serve this capability, including ones the runtime does not fail over to. */
+    upstreams?: CatalogUpstream[];
+    /** Upstream routes (from `proxy.ts`) when the capability is served by proxying to hubs. */
+    proxy?: ProxySpec<z.output<I>, z.input<O>>;
+    handler: (input: z.output<I>, ctx: Ctx) => Promise<z.input<O>>;
+}
+export type AnyCapability = CapabilityDefinition<z.ZodType, z.ZodType>;
+/** Our own `handler`, or a `proxy` spec whose routes `ctx.upstream` runs. A handler wins when both are given. */
+export type CapabilitySpec<I extends z.ZodType, O extends z.ZodType> = Omit<CapabilityDefinition<I, O>, 'handler'> & {
+    handler?: CapabilityDefinition<I, O>['handler'];
+};
+export declare function defineCapability<I extends z.ZodType, O extends z.ZodType>(spec: CapabilitySpec<I, O>): CapabilityDefinition<I, O>;
+/** Hubs a served capability can call. Typed proxies fail over across every route; pass-through sets `upstreams` itself. */
+export declare function upstreamsOf(impl: AnyCapability | undefined): CatalogUpstream[];

package/dist/capability.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function defineCapability(spec) {
+    const { proxy, handler } = spec;
+    if (!handler && !proxy)
+        throw new Error(`Capability ${spec.slug} needs a handler or a proxy`);
+    if (proxy && proxy.routes.length === 0)
+        throw new Error(`Capability ${spec.slug} has a proxy with no routes`);
+    const definition = {
+        ...spec,
+        proxy: handler ? undefined : proxy,
+        handler: handler ?? ((input, ctx) => ctx.upstream.run(spec.slug, proxy, input, { signal: ctx.signal, callerId: ctx.auth.callerId })),
+    };
+    if (!SLUG.test(definition.slug)) {
+        throw new Error(`Invalid capability slug: ${definition.slug}`);
+    }
+    if (definition.limits.timeoutMs <= 0 || definition.limits.maxInputBytes <= 0) {
+        throw new Error(`Capability ${definition.slug} must set positive limits`);
+    }
+    if (!(definition.input instanceof z.ZodObject)) {
+        throw new Error(`Capability ${definition.slug} input must be a z.object so it maps to an MCP tool`);
+    }
+    return Object.freeze(definition);
+}
+/** Hubs a served capability can call. Typed proxies fail over across every route; pass-through sets `upstreams` itself. */
+export function upstreamsOf(impl) {
+    if (!impl)
+        return [];
+    if (impl.upstreams)
+        return impl.upstreams;
+    const routes = impl.proxy?.routes ?? [];
+    const failover = routes.length > 1;
+    return routes.map((route) => ({
+        hub: route.hub,
+        api: route.api ?? null,
+        priceUsd: route.priceUsd ?? null,
+        failover,
+    }));
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../../../packages/core/src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAqDxB,MAAM,IAAI,GAAG,4BAA4B,CAAC;AAE1C,MAAM,UAAU,gBAAgB,CAA2C,IAA0B;IACnG,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,IAAI,6BAA6B,CAAC,CAAC;IAC9F,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,IAAI,6BAA6B,CAAC,CAAC;IAC9G,MAAM,UAAU,GAA+B;QAC7C,GAAG,IAAI;QACP,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK;QAClC,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,KAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;KACtI,CAAC;IACF,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,aAAa,IAAI,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,KAAK,CAAC,cAAc,UAAU,CAAC,IAAI,2BAA2B,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,cAAc,UAAU,CAAC,IAAI,qDAAqD,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACnC,CAAC;AAED,2HAA2H;AAC3H,MAAM,UAAU,WAAW,CAAC,IAA+B;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,IAAI,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,IAAI;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,QAAQ;KACT,CAAC,CAAC,CAAC;AACN,CAAC","sourcesContent":["import { z } from 'zod';\nimport type { Requirement } from './connections.ts';\nimport type { Ctx } from './context.ts';\nimport type { ProxySpec } from './upstream-types.ts';\nimport type { Sourcing } from './registry-types.ts';\n\nexport type CapabilityMode = 'sync' | 'job';\n\nexport interface CapabilityLimits {\n  timeoutMs: number;\n  maxInputBytes: number;\n}\n\n/** A hub that can serve this capability. `failover` is true when the runtime may call it with the same input. */\nexport interface CatalogUpstream {\n  hub: string;\n  api: string | null;\n  priceUsd: number | null;\n  failover: boolean;\n}\n\nexport interface CapabilityDefinition<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {\n  /** Exactly the workbook's Capability value. */\n  slug: string;\n  /** One sentence, in our own words. */\n  summary: string;\n  input: I;\n  output: O;\n  sourcing: Sourcing;\n  mode: CapabilityMode;\n  limits: CapabilityLimits;\n  /** x12i packages actually used, after verification. */\n  reuse: string[];\n  /** Engineer-days actually spent, for the next sizing round. */\n  actualDays?: number;\n  /** Operator-configured services the handler needs; drives `connected` and `missing` in the catalog. */\n  requires?: Requirement[];\n  /** Example input used by docs and the contract check. */\n  examples?: z.input<I>[];\n  /** Hubs that can serve this capability, including ones the runtime does not fail over to. */\n  upstreams?: CatalogUpstream[];\n  /** Upstream routes (from `proxy.ts`) when the capability is served by proxying to hubs. */\n  proxy?: ProxySpec<z.output<I>, z.input<O>>;\n  handler: (input: z.output<I>, ctx: Ctx) => Promise<z.input<O>>;\n}\n\nexport type AnyCapability = CapabilityDefinition<z.ZodType, z.ZodType>;\n\n/** Our own `handler`, or a `proxy` spec whose routes `ctx.upstream` runs. A handler wins when both are given. */\nexport type CapabilitySpec<I extends z.ZodType, O extends z.ZodType> = Omit<CapabilityDefinition<I, O>, 'handler'> & {\n  handler?: CapabilityDefinition<I, O>['handler'];\n};\n\nconst SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;\n\nexport function defineCapability<I extends z.ZodType, O extends z.ZodType>(spec: CapabilitySpec<I, O>): CapabilityDefinition<I, O> {\n  const { proxy, handler } = spec;\n  if (!handler && !proxy) throw new Error(`Capability ${spec.slug} needs a handler or a proxy`);\n  if (proxy && proxy.routes.length === 0) throw new Error(`Capability ${spec.slug} has a proxy with no routes`);\n  const definition: CapabilityDefinition<I, O> = {\n    ...spec,\n    proxy: handler ? undefined : proxy,\n    handler: handler ?? ((input, ctx) => ctx.upstream.run(spec.slug, proxy!, input, { signal: ctx.signal, callerId: ctx.auth.callerId })),\n  };\n  if (!SLUG.test(definition.slug)) {\n    throw new Error(`Invalid capability slug: ${definition.slug}`);\n  }\n  if (definition.limits.timeoutMs <= 0 || definition.limits.maxInputBytes <= 0) {\n    throw new Error(`Capability ${definition.slug} must set positive limits`);\n  }\n  if (!(definition.input instanceof z.ZodObject)) {\n    throw new Error(`Capability ${definition.slug} input must be a z.object so it maps to an MCP tool`);\n  }\n  return Object.freeze(definition);\n}\n\n/** Hubs a served capability can call. Typed proxies fail over across every route; pass-through sets `upstreams` itself. */\nexport function upstreamsOf(impl: AnyCapability | undefined): CatalogUpstream[] {\n  if (!impl) return [];\n  if (impl.upstreams) return impl.upstreams;\n  const routes = impl.proxy?.routes ?? [];\n  const failover = routes.length > 1;\n  return routes.map((route) => ({\n    hub: route.hub,\n    api: route.api ?? null,\n    priceUsd: route.priceUsd ?? null,\n    failover,\n  }));\n}\n"]}

package/dist/connections.d.ts

@@ -0,0 +1,42 @@
+import type { ServiceId } from './services.js';
+/** Something a served capability needs before it can answer. Values are never exposed, only variable names. */
+export type MissingItem = {
+    kind: 'service';
+    service: string;
+    env: string[];
+} | {
+    kind: 'hub';
+    hub: string;
+    env: string;
+    missing: 'key' | 'consent' | 'wallet';
+};
+export interface ConnectionInfo {
+    /** `null` when the capability is not served at all (planned, connector, blocked-terms and so on). */
+    connected: boolean | null;
+    missing: MissingItem[];
+}
+export interface Requirement {
+    service: ServiceId;
+}
+/** One row of GET /v1/connections. */
+export interface ConnectionEntry {
+    kind: 'service' | 'hub';
+    id: string;
+    title: string;
+    connected: boolean;
+    /** Variable names that connect it (alternatives joined with " or "). */
+    env: string[];
+    missingEnv: string[];
+    /** Capabilities that become callable once this is connected. */
+    unlocks: number;
+    docs: string;
+    note?: string;
+}
+/**
+ * Supplies connection state for capabilities served through something other than our own
+ * handlers, such as the upstream proxy layer.
+ */
+export interface ConnectionProvider {
+    capability(slug: string): ConnectionInfo | undefined;
+    entries(): ConnectionEntry[];
+}

package/dist/connections.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connections.js.map

package/dist/connections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../../../../packages/core/src/connections.ts"],"names":[],"mappings":"","sourcesContent":["import type { ServiceId } from './services.ts';\n\n/** Something a served capability needs before it can answer. Values are never exposed, only variable names. */\nexport type MissingItem =\n  | { kind: 'service'; service: string; env: string[] }\n  | { kind: 'hub'; hub: string; env: string; missing: 'key' | 'consent' | 'wallet' };\n\nexport interface ConnectionInfo {\n  /** `null` when the capability is not served at all (planned, connector, blocked-terms and so on). */\n  connected: boolean | null;\n  missing: MissingItem[];\n}\n\nexport interface Requirement {\n  service: ServiceId;\n}\n\n/** One row of GET /v1/connections. */\nexport interface ConnectionEntry {\n  kind: 'service' | 'hub';\n  id: string;\n  title: string;\n  connected: boolean;\n  /** Variable names that connect it (alternatives joined with \" or \"). */\n  env: string[];\n  missingEnv: string[];\n  /** Capabilities that become callable once this is connected. */\n  unlocks: number;\n  docs: string;\n  note?: string;\n}\n\n/**\n * Supplies connection state for capabilities served through something other than our own\n * handlers, such as the upstream proxy layer.\n */\nexport interface ConnectionProvider {\n  capability(slug: string): ConnectionInfo | undefined;\n  entries(): ConnectionEntry[];\n}\n"]}

package/dist/context.d.ts

@@ -0,0 +1,216 @@
+import type { z } from 'zod';
+import type { Dns } from './dns-types.js';
+import { type Logger } from './logger.js';
+import { type ServiceId } from './services.js';
+import type { UpstreamClient } from './upstream-types.js';
+/** Opaque caller identity, provided by the auth layer outside this repo. Never inspect tokens. */
+export interface AuthContext {
+    readonly callerId: string;
+    readonly opaque?: unknown;
+}
+export type Meter = (units: number) => void;
+export interface SafeFetchOptions {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+    maxBytes?: number;
+    /** Return the first `maxBytes` (with `truncated: true`) instead of failing with `limit_exceeded`. */
+    truncate?: boolean;
+    timeoutMs?: number;
+    maxRedirects?: number;
+    /** Check robots.txt before fetching. Defaults to false; crawling capabilities must set it. */
+    respectRobots?: boolean;
+    userAgent?: string;
+    signal?: AbortSignal;
+}
+export interface SafeResponse {
+    requestedUrl: string;
+    url: string;
+    status: number;
+    /** Lower-case names. Repeated headers are joined with ", ", except Set-Cookie, which is joined with "\n". */
+    headers: Record<string, string>;
+    redirects: string[];
+    remoteAddress: string;
+    body: Uint8Array;
+    truncated: boolean;
+    text(): string;
+    json<T = unknown>(): T;
+}
+export type SafeFetch = (url: string, options?: SafeFetchOptions) => Promise<SafeResponse>;
+export interface PromptSource {
+    /** Stable id, e.g. `sentiment-analyze/classify@v1`. */
+    id: string;
+    /** Template text with `{{name}}` placeholders. */
+    template: string;
+}
+export interface LlmJsonRequest<S extends z.ZodType> {
+    prompt: PromptSource;
+    variables?: Record<string, string>;
+    schema: S;
+    temperature?: number;
+    maxOutputTokens?: number;
+    signal?: AbortSignal;
+}
+export interface LlmTextRequest {
+    prompt: PromptSource;
+    variables?: Record<string, string>;
+    temperature?: number;
+    maxOutputTokens?: number;
+    signal?: AbortSignal;
+}
+export interface LlmChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** A caller-built conversation sent as is, for chat-completion capabilities. No prompt template is involved. */
+export interface LlmChatRequest {
+    messages: LlmChatMessage[];
+    /** Stable id for logs and recorded fixtures, e.g. `llm-chat-completion/chat`. */
+    id?: string;
+    temperature?: number;
+    maxOutputTokens?: number;
+    signal?: AbortSignal;
+}
+export interface LlmChatResult {
+    text: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface LlmClient {
+    generateJson<S extends z.ZodType>(request: LlmJsonRequest<S>): Promise<z.infer<S>>;
+    generateText(request: LlmTextRequest): Promise<string>;
+    chat(request: LlmChatRequest): Promise<LlmChatResult>;
+}
+export interface ModelRunRequest {
+    model: string;
+    input: Record<string, unknown>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface ModelOutput {
+    model: string;
+    /** Normalised outputs: text, URLs of produced files, or structured data. */
+    text?: string;
+    files?: {
+        url: string;
+        contentType?: string;
+    }[];
+    data?: unknown;
+}
+export interface ModelsClient {
+    run(request: ModelRunRequest): Promise<ModelOutput>;
+}
+export type SearchKind = 'web' | 'news';
+export type SearchTimeRange = 'day' | 'week' | 'month' | 'year';
+export interface WebSearchRequest {
+    query: string;
+    kind?: SearchKind;
+    limit?: number;
+    /** ISO 3166-1 alpha-2, lower case. */
+    country?: string;
+    /** ISO 639-1. */
+    language?: string;
+    timeRange?: SearchTimeRange;
+    signal?: AbortSignal;
+}
+export interface WebSearchResult {
+    position: number;
+    title: string;
+    url: string;
+    domain: string;
+    snippet?: string;
+    /** As the provider shows it; not always an ISO date. */
+    date?: string;
+}
+export interface WebSearchResponse {
+    provider: string;
+    query: string;
+    results: WebSearchResult[];
+    /** Short answer when the provider returns one. Not verified. */
+    answer?: string;
+}
+/** Operator-configured web search (`@x12i/api-hub-search`). */
+export interface WebSearch {
+    search(request: WebSearchRequest): Promise<WebSearchResponse>;
+}
+export type CacheTtl = '6h' | '24h' | number;
+export interface Cache {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttl: CacheTtl): Promise<void>;
+    wrap<T>(key: string, ttl: CacheTtl, fn: () => Promise<T>): Promise<T>;
+}
+export interface StoredFile {
+    key: string;
+    url: string;
+    contentType: string;
+    bytes: number;
+    expiresAt: string;
+}
+export interface Files {
+    decodeBase64(data: string, options?: {
+        maxBytes?: number;
+    }): Uint8Array;
+    put(bytes: Uint8Array, options: {
+        contentType: string;
+        ttlSeconds?: number;
+    }): Promise<StoredFile>;
+    get(key: string): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+    } | undefined>;
+}
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+export interface JobRecord {
+    id: string;
+    capability: string;
+    status: JobStatus;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/** Async job runner (F1), implemented by `@x12i/api-hub-jobs`. */
+export interface JobRunner {
+    submit(capability: import('./capability.js').AnyCapability, input: unknown, auth: AuthContext, makeCtx: (signal: AbortSignal) => Ctx): Promise<JobRecord>;
+    get(id: string, auth: AuthContext): Promise<JobRecord | undefined>;
+}
+export interface Ctx {
+    auth: AuthContext;
+    meter: Meter;
+    log: Logger;
+    fetch: SafeFetch;
+    dns: Dns;
+    llm: LlmClient;
+    models: ModelsClient;
+    search: WebSearch;
+    cache: Cache;
+    files: Files;
+    /** Proxy runner for capabilities served by upstream hubs (`@x12i/api-hub-upstream`). */
+    upstream: UpstreamClient;
+    /**
+     * Operator-configured variables of a service the capability lists in `requires`, keyed by variable name.
+     * Throws `service_not_connected` when they are not set. Never log or return the values.
+     */
+    credentials: (service: ServiceId) => Record<string, string>;
+    signal: AbortSignal;
+}
+export declare const stubFetch: SafeFetch;
+export declare const stubDns: Dns;
+export declare const stubLlm: LlmClient;
+export declare const stubModels: ModelsClient;
+export declare const stubSearch: WebSearch;
+export declare function createNoopCache(): Cache;
+export declare const stubFiles: Files;
+/** No upstream layer wired: every proxied call reports that none of its hubs is connected. */
+export declare const stubUpstream: UpstreamClient;
+export declare const stubCredentials: (service: ServiceId) => never;
+export declare const anonymousAuth: AuthContext;
+/** Billing is solved elsewhere; this stub only exists so capabilities call it at the right moment. */
+export declare const noopMeter: Meter;
+export declare function createStubContext(overrides?: Partial<Ctx>): Ctx;

package/dist/context.js

@@ -0,0 +1,81 @@
+import { HubError } from "./errors.js";
+import { createLogger } from "./logger.js";
+import { serviceNotConnected } from "./services.js";
+function notConfigured(what) {
+    throw new HubError('unsupported', `${what} is not configured on this server`);
+}
+export const stubFetch = async () => notConfigured('Outbound fetching');
+export const stubDns = {
+    resolve: async () => notConfigured('DNS resolution'),
+    mailRecords: async () => notConfigured('DNS resolution'),
+    reverse: async () => notConfigured('DNS resolution'),
+    tlsCertificate: async () => notConfigured('TLS inspection'),
+};
+export const stubLlm = {
+    generateJson: async () => {
+        throw serviceNotConnected('llm');
+    },
+    generateText: async () => {
+        throw serviceNotConnected('llm');
+    },
+    chat: async () => {
+        throw serviceNotConnected('llm');
+    },
+};
+export const stubModels = {
+    run: async () => {
+        throw serviceNotConnected('models');
+    },
+};
+export const stubSearch = {
+    search: async () => {
+        throw serviceNotConnected('search');
+    },
+};
+export function createNoopCache() {
+    return {
+        get: async () => undefined,
+        set: async () => undefined,
+        wrap: async (_key, _ttl, fn) => fn(),
+    };
+}
+export const stubFiles = {
+    decodeBase64: () => notConfigured('File handling'),
+    put: async () => notConfigured('File storage'),
+    get: async () => notConfigured('File storage'),
+};
+/** No upstream layer wired: every proxied call reports that none of its hubs is connected. */
+export const stubUpstream = {
+    run: async (slug, spec) => {
+        throw new HubError('hub_not_connected', `No hub that sells ${slug} is connected on this server`, {
+            reason: spec.routes.length ? 'missing_key' : 'no_hub_available',
+            hubs: spec.routes.map((r) => ({ hub: r.hub, missing: 'key' })),
+            docs: 'docs/ENV.md#hubs',
+        });
+    },
+};
+export const stubCredentials = (service) => {
+    throw serviceNotConnected(service);
+};
+export const anonymousAuth = { callerId: 'anonymous' };
+/** Billing is solved elsewhere; this stub only exists so capabilities call it at the right moment. */
+export const noopMeter = () => undefined;
+export function createStubContext(overrides = {}) {
+    return {
+        auth: anonymousAuth,
+        meter: noopMeter,
+        log: createLogger({ level: 'silent' }),
+        fetch: stubFetch,
+        dns: stubDns,
+        llm: stubLlm,
+        models: stubModels,
+        search: stubSearch,
+        cache: createNoopCache(),
+        files: stubFiles,
+        upstream: stubUpstream,
+        credentials: stubCredentials,
+        signal: new AbortController().signal,
+        ...overrides,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../../packages/core/src/context.ts"],"names":[],"mappings":"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","sourcesContent":["import type { z } from 'zod';\nimport type { Dns } from './dns-types.ts';\nimport { HubError } from './errors.ts';\nimport { createLogger, type Logger } from './logger.ts';\nimport { serviceNotConnected, type ServiceId } from './services.ts';\nimport type { UpstreamClient } from './upstream-types.ts';\n\n/** Opaque caller identity, provided by the auth layer outside this repo. Never inspect tokens. */\nexport interface AuthContext {\n  readonly callerId: string;\n  readonly opaque?: unknown;\n}\n\nexport type Meter = (units: number) => void;\n\nexport interface SafeFetchOptions {\n  method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n  headers?: Record<string, string>;\n  body?: string | Uint8Array;\n  maxBytes?: number;\n  /** Return the first `maxBytes` (with `truncated: true`) instead of failing with `limit_exceeded`. */\n  truncate?: boolean;\n  timeoutMs?: number;\n  maxRedirects?: number;\n  /** Check robots.txt before fetching. Defaults to false; crawling capabilities must set it. */\n  respectRobots?: boolean;\n  userAgent?: string;\n  signal?: AbortSignal;\n}\n\nexport interface SafeResponse {\n  requestedUrl: string;\n  url: string;\n  status: number;\n  /** Lower-case names. Repeated headers are joined with \", \", except Set-Cookie, which is joined with \"\\n\". */\n  headers: Record<string, string>;\n  redirects: string[];\n  remoteAddress: string;\n  body: Uint8Array;\n  truncated: boolean;\n  text(): string;\n  json<T = unknown>(): T;\n}\n\nexport type SafeFetch = (url: string, options?: SafeFetchOptions) => Promise<SafeResponse>;\n\nexport interface PromptSource {\n  /** Stable id, e.g. `sentiment-analyze/classify@v1`. */\n  id: string;\n  /** Template text with `{{name}}` placeholders. */\n  template: string;\n}\n\nexport interface LlmJsonRequest<S extends z.ZodType> {\n  prompt: PromptSource;\n  variables?: Record<string, string>;\n  schema: S;\n  temperature?: number;\n  maxOutputTokens?: number;\n  signal?: AbortSignal;\n}\n\nexport interface LlmTextRequest {\n  prompt: PromptSource;\n  variables?: Record<string, string>;\n  temperature?: number;\n  maxOutputTokens?: number;\n  signal?: AbortSignal;\n}\n\nexport interface LlmChatMessage {\n  role: 'system' | 'user' | 'assistant';\n  content: string;\n}\n\n/** A caller-built conversation sent as is, for chat-completion capabilities. No prompt template is involved. */\nexport interface LlmChatRequest {\n  messages: LlmChatMessage[];\n  /** Stable id for logs and recorded fixtures, e.g. `llm-chat-completion/chat`. */\n  id?: string;\n  temperature?: number;\n  maxOutputTokens?: number;\n  signal?: AbortSignal;\n}\n\nexport interface LlmChatResult {\n  text: string;\n  model?: string;\n  inputTokens?: number;\n  outputTokens?: number;\n}\n\nexport interface LlmClient {\n  generateJson<S extends z.ZodType>(request: LlmJsonRequest<S>): Promise<z.infer<S>>;\n  generateText(request: LlmTextRequest): Promise<string>;\n  chat(request: LlmChatRequest): Promise<LlmChatResult>;\n}\n\nexport interface ModelRunRequest {\n  model: string;\n  input: Record<string, unknown>;\n  signal?: AbortSignal;\n  timeoutMs?: number;\n}\n\nexport interface ModelOutput {\n  model: string;\n  /** Normalised outputs: text, URLs of produced files, or structured data. */\n  text?: string;\n  files?: { url: string; contentType?: string }[];\n  data?: unknown;\n}\n\nexport interface ModelsClient {\n  run(request: ModelRunRequest): Promise<ModelOutput>;\n}\n\nexport type SearchKind = 'web' | 'news';\nexport type SearchTimeRange = 'day' | 'week' | 'month' | 'year';\n\nexport interface WebSearchRequest {\n  query: string;\n  kind?: SearchKind;\n  limit?: number;\n  /** ISO 3166-1 alpha-2, lower case. */\n  country?: string;\n  /** ISO 639-1. */\n  language?: string;\n  timeRange?: SearchTimeRange;\n  signal?: AbortSignal;\n}\n\nexport interface WebSearchResult {\n  position: number;\n  title: string;\n  url: string;\n  domain: string;\n  snippet?: string;\n  /** As the provider shows it; not always an ISO date. */\n  date?: string;\n}\n\nexport interface WebSearchResponse {\n  provider: string;\n  query: string;\n  results: WebSearchResult[];\n  /** Short answer when the provider returns one. Not verified. */\n  answer?: string;\n}\n\n/** Operator-configured web search (`@x12i/api-hub-search`). */\nexport interface WebSearch {\n  search(request: WebSearchRequest): Promise<WebSearchResponse>;\n}\n\nexport type CacheTtl = '6h' | '24h' | number;\n\nexport interface Cache {\n  get<T>(key: string): Promise<T | undefined>;\n  set<T>(key: string, value: T, ttl: CacheTtl): Promise<void>;\n  wrap<T>(key: string, ttl: CacheTtl, fn: () => Promise<T>): Promise<T>;\n}\n\nexport interface StoredFile {\n  key: string;\n  url: string;\n  contentType: string;\n  bytes: number;\n  expiresAt: string;\n}\n\nexport interface Files {\n  decodeBase64(data: string, options?: { maxBytes?: number }): Uint8Array;\n  put(bytes: Uint8Array, options: { contentType: string; ttlSeconds?: number }): Promise<StoredFile>;\n  get(key: string): Promise<{ bytes: Uint8Array; contentType: string } | undefined>;\n}\n\nexport type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed';\n\nexport interface JobRecord {\n  id: string;\n  capability: string;\n  status: JobStatus;\n  createdAt: string;\n  updatedAt: string;\n  expiresAt: string;\n  result?: unknown;\n  error?: { code: string; message: string; details?: unknown };\n}\n\n/** Async job runner (F1), implemented by `@x12i/api-hub-jobs`. */\nexport interface JobRunner {\n  submit(\n    capability: import('./capability.ts').AnyCapability,\n    input: unknown,\n    auth: AuthContext,\n    makeCtx: (signal: AbortSignal) => Ctx,\n  ): Promise<JobRecord>;\n  get(id: string, auth: AuthContext): Promise<JobRecord | undefined>;\n}\n\nexport interface Ctx {\n  auth: AuthContext;\n  meter: Meter;\n  log: Logger;\n  fetch: SafeFetch;\n  dns: Dns;\n  llm: LlmClient;\n  models: ModelsClient;\n  search: WebSearch;\n  cache: Cache;\n  files: Files;\n  /** Proxy runner for capabilities served by upstream hubs (`@x12i/api-hub-upstream`). */\n  upstream: UpstreamClient;\n  /**\n   * Operator-configured variables of a service the capability lists in `requires`, keyed by variable name.\n   * Throws `service_not_connected` when they are not set. Never log or return the values.\n   */\n  credentials: (service: ServiceId) => Record<string, string>;\n  signal: AbortSignal;\n}\n\nfunction notConfigured(what: string): never {\n  throw new HubError('unsupported', `${what} is not configured on this server`);\n}\n\nexport const stubFetch: SafeFetch = async () => notConfigured('Outbound fetching');\n\nexport const stubDns: Dns = {\n  resolve: async () => notConfigured('DNS resolution'),\n  mailRecords: async () => notConfigured('DNS resolution'),\n  reverse: async () => notConfigured('DNS resolution'),\n  tlsCertificate: async () => notConfigured('TLS inspection'),\n};\n\nexport const stubLlm: LlmClient = {\n  generateJson: async () => {\n    throw serviceNotConnected('llm');\n  },\n  generateText: async () => {\n    throw serviceNotConnected('llm');\n  },\n  chat: async () => {\n    throw serviceNotConnected('llm');\n  },\n};\n\nexport const stubModels: ModelsClient = {\n  run: async () => {\n    throw serviceNotConnected('models');\n  },\n};\n\nexport const stubSearch: WebSearch = {\n  search: async () => {\n    throw serviceNotConnected('search');\n  },\n};\n\nexport function createNoopCache(): Cache {\n  return {\n    get: async () => undefined,\n    set: async () => undefined,\n    wrap: async (_key, _ttl, fn) => fn(),\n  };\n}\n\nexport const stubFiles: Files = {\n  decodeBase64: () => notConfigured('File handling'),\n  put: async () => notConfigured('File storage'),\n  get: async () => notConfigured('File storage'),\n};\n\n/** No upstream layer wired: every proxied call reports that none of its hubs is connected. */\nexport const stubUpstream: UpstreamClient = {\n  run: async (slug, spec) => {\n    throw new HubError('hub_not_connected', `No hub that sells ${slug} is connected on this server`, {\n      reason: spec.routes.length ? 'missing_key' : 'no_hub_available',\n      hubs: spec.routes.map((r) => ({ hub: r.hub, missing: 'key' })),\n      docs: 'docs/ENV.md#hubs',\n    });\n  },\n};\n\nexport const stubCredentials = (service: ServiceId): never => {\n  throw serviceNotConnected(service);\n};\n\nexport const anonymousAuth: AuthContext = { callerId: 'anonymous' };\n\n/** Billing is solved elsewhere; this stub only exists so capabilities call it at the right moment. */\nexport const noopMeter: Meter = () => undefined;\n\nexport function createStubContext(overrides: Partial<Ctx> = {}): Ctx {\n  return {\n    auth: anonymousAuth,\n    meter: noopMeter,\n    log: createLogger({ level: 'silent' }),\n    fetch: stubFetch,\n    dns: stubDns,\n    llm: stubLlm,\n    models: stubModels,\n    search: stubSearch,\n    cache: createNoopCache(),\n    files: stubFiles,\n    upstream: stubUpstream,\n    credentials: stubCredentials,\n    signal: new AbortController().signal,\n    ...overrides,\n  };\n}\n"]}

package/dist/dns-types.d.ts

@@ -0,0 +1,64 @@
+export declare const DNS_RECORD_TYPES: readonly ["A", "AAAA", "CNAME", "MX", "NS", "TXT", "SOA", "CAA", "SRV"];
+export type DnsRecordType = (typeof DNS_RECORD_TYPES)[number];
+export interface DnsRecord {
+    type: DnsRecordType;
+    value: string;
+    priority?: number;
+    ttl?: number;
+}
+export interface SpfRecord {
+    raw: string;
+    mechanisms: {
+        qualifier: '+' | '-' | '~' | '?';
+        type: string;
+        value?: string;
+    }[];
+    all: '+' | '-' | '~' | '?' | null;
+    includes: string[];
+    lookupCount: number;
+}
+export interface DmarcRecord {
+    raw: string;
+    policy: 'none' | 'quarantine' | 'reject' | null;
+    subdomainPolicy: 'none' | 'quarantine' | 'reject' | null;
+    pct: number;
+    rua: string[];
+    ruf: string[];
+    adkim: 'r' | 's';
+    aspf: 'r' | 's';
+}
+export interface MailRecords {
+    domain: string;
+    mx: {
+        exchange: string;
+        priority: number;
+    }[];
+    nullMx: boolean;
+    spf: SpfRecord | null;
+    spfRecords: number;
+    dmarc: DmarcRecord | null;
+}
+export interface TlsCertificateInfo {
+    host: string;
+    port: number;
+    remoteAddress: string;
+    authorized: boolean;
+    authorizationError: string | null;
+    protocol: string | null;
+    subject: Record<string, string>;
+    issuer: Record<string, string>;
+    subjectAltNames: string[];
+    validFrom: string;
+    validTo: string;
+    daysRemaining: number;
+    serialNumber: string;
+    fingerprint256: string;
+}
+/** DNS and mail helper (F7), implemented by `@x12i/api-hub-dns`. Names are validated and IDN-normalised by the implementation. */
+export interface Dns {
+    resolve(name: string, type: DnsRecordType): Promise<DnsRecord[]>;
+    mailRecords(domain: string): Promise<MailRecords>;
+    /** PTR names of a public IPv4 or IPv6 address; empty when none are published. */
+    reverse(ip: string): Promise<string[]>;
+    tlsCertificate(host: string, port?: number, timeoutMs?: number): Promise<TlsCertificateInfo>;
+}

package/dist/dns-types.js

@@ -0,0 +1,2 @@
+export const DNS_RECORD_TYPES = ['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT', 'SOA', 'CAA', 'SRV'];
+//# sourceMappingURL=dns-types.js.map

package/dist/dns-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns-types.js","sourceRoot":"","sources":["../../../../../packages/core/src/dns-types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC","sourcesContent":["export const DNS_RECORD_TYPES = ['A', 'AAAA', 'CNAME', 'MX', 'NS', 'TXT', 'SOA', 'CAA', 'SRV'] as const;\nexport type DnsRecordType = (typeof DNS_RECORD_TYPES)[number];\n\nexport interface DnsRecord {\n  type: DnsRecordType;\n  value: string;\n  priority?: number;\n  ttl?: number;\n}\n\nexport interface SpfRecord {\n  raw: string;\n  mechanisms: { qualifier: '+' | '-' | '~' | '?'; type: string; value?: string }[];\n  all: '+' | '-' | '~' | '?' | null;\n  includes: string[];\n  lookupCount: number;\n}\n\nexport interface DmarcRecord {\n  raw: string;\n  policy: 'none' | 'quarantine' | 'reject' | null;\n  subdomainPolicy: 'none' | 'quarantine' | 'reject' | null;\n  pct: number;\n  rua: string[];\n  ruf: string[];\n  adkim: 'r' | 's';\n  aspf: 'r' | 's';\n}\n\nexport interface MailRecords {\n  domain: string;\n  mx: { exchange: string; priority: number }[];\n  nullMx: boolean;\n  spf: SpfRecord | null;\n  spfRecords: number;\n  dmarc: DmarcRecord | null;\n}\n\nexport interface TlsCertificateInfo {\n  host: string;\n  port: number;\n  remoteAddress: string;\n  authorized: boolean;\n  authorizationError: string | null;\n  protocol: string | null;\n  subject: Record<string, string>;\n  issuer: Record<string, string>;\n  subjectAltNames: string[];\n  validFrom: string;\n  validTo: string;\n  daysRemaining: number;\n  serialNumber: string;\n  fingerprint256: string;\n}\n\n/** DNS and mail helper (F7), implemented by `@x12i/api-hub-dns`. Names are validated and IDN-normalised by the implementation. */\nexport interface Dns {\n  resolve(name: string, type: DnsRecordType): Promise<DnsRecord[]>;\n  mailRecords(domain: string): Promise<MailRecords>;\n  /** PTR names of a public IPv4 or IPv6 address; empty when none are published. */\n  reverse(ip: string): Promise<string[]>;\n  tlsCertificate(host: string, port?: number, timeoutMs?: number): Promise<TlsCertificateInfo>;\n}\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export declare const ERROR_CODES: readonly ["invalid_input", "limit_exceeded", "timeout", "unsupported", "upstream_unavailable", "not_permitted", "internal", "service_not_connected", "hub_not_connected", "spend_limit_reached"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export interface ErrorBody {
+    error: {
+        code: ErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+export declare const HTTP_STATUS: Record<ErrorCode, number>;
+/** One line per code, rendered into docs/ERRORS.md. */
+export declare const ERROR_DESCRIPTIONS: Record<ErrorCode, {
+    when: string;
+    details: string;
+    callerAction: string;
+}>;
+export declare class HubError extends Error {
+    readonly code: ErrorCode;
+    readonly details: unknown;
+    constructor(code: ErrorCode, message: string, details?: unknown);
+    get httpStatus(): number;
+    toBody(): ErrorBody;
+}
+export declare function isHubError(err: unknown): err is HubError;
+export declare function toHubError(err: unknown): HubError;