@x12i/sdk 0.3.0 → 1.0.0

package/dist/cli.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { X12iClient } from "./client.js";
+import { loadOrCreateIdentity } from "./identity.js";
+import { parseInitArgs, writeInit } from "./init.js";
+import { runAdminCli } from "./admin.js";
+import { serveMcp } from "./mcp.js";
+const [command, ...rest] = process.argv.slice(2);
+if (command === "mcp") {
+    await serveMcp(new X12iClient());
+}
+else if (command === "init") {
+    const options = parseInitArgs(rest);
+    const identity = await loadOrCreateIdentity();
+    const files = await writeInit(options);
+    process.stdout.write(`${JSON.stringify({ identity: identity.fingerprint, files }, null, 2)}\n`);
+}
+else if (command === "admin") {
+    await runAdminCli(rest);
+}
+else if (command === "readme" || command === "package") {
+    const name = rest[0];
+    if (!name) {
+        process.stderr.write(`Usage: x12i-sdk ${command} <package>\n`);
+        process.exitCode = 1;
+    }
+    else {
+        const view = command === "readme" ? await new X12iClient().readme(name) : await new X12iClient().package(name);
+        process.stdout.write(command === "readme" ? formatReadme(view) : `${JSON.stringify(view, null, 2)}\n`);
+    }
+}
+else {
+    process.stdout.write(`x12i-sdk readme <package>
+  Print the cached README, then the current one when the catalog knows the package was published again.
+
+x12i-sdk package <package>
+  Print the cached package record, then refresh it when a newer publish is known.
+
+x12i-sdk mcp
+  Start the stdio MCP server. Cursor, Claude Code, and Codex use this to search the @x12i catalog.
+
+x12i-sdk init [--cursor] [--claude] [--codex] [--all] [--global] [--dir path]
+  Write the x12i MCP server into the current project. Cursor is the default.
+  --all writes Cursor, Claude Code, and Codex. --global writes user-level config for every agent.
+
+x12i-sdk admin catalog
+  Print the entire catalog as JSON. x12i-sdk admin shows the update commands.
+
+Set X12I_SDK_URL to point at a local catalog service. The default host is https://x12i-sdk.x12i.com.
+Admin updates use X12I_SDK_ADMIN_KEY. Reviews and reports stay on the commands above.
+`);
+}
+function formatReadme(view) {
+    if (view.source === "registry") {
+        return `The catalog service was unreachable. This README is from the npm registry.\n\n${view.readme}\n`;
+    }
+    if (view.cached.readmeStatus === "fresh") {
+        return `${view.name}\n\n${view.readme || "No README yet."}\n`;
+    }
+    const cachedText = view.cached.readme || "No README cached yet.";
+    if (view.refreshError) {
+        return `${view.name} · cached\n\n${cachedText}\n\nRefresh failed: ${view.refreshError}\n`;
+    }
+    if (!view.updated) {
+        return `${view.name} · cached\n\n${cachedText}\n\nThe latest publish matches this README.\n`;
+    }
+    return `${view.name} · cached\n\n${cachedText}\n\n---\nupdated\n\n${view.readme || "No README yet."}\n`;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -1,120 +1,76 @@
-import { ParserRegistry, type ClassifyCandidate, type FetchResult, type ParsedResult, type Parser } from "@x12i/core";
-import { type FetchOptions, type RetrieveOptions, type RetrieveBatchItem, type FetchCache, type SnapshotStore, type CachedRetrieveOptions, type ChangeCheckRequest, type ChangeCheckResult } from "@x12i/fetcher";
-import { type IngestOptions, type IngestResult } from "@x12i/ingest";
-import { type SearchConfig, type SearchProvider, type WebSearchRequest, type WebSearchResponse } from "@x12i/search";
-import { type CrawlRequest, type CrawlResult } from "@x12i/crawl";
-import { type ResearchPacket, type ResearchRequest } from "@x12i/research";
-import { type ExtractRequest, type ExtractResult, type ExtractionAdapter } from "@x12i/extract";
-import { type RunRecord, type RunStore, type ListItemsOptions, type ListItemsResult } from "@x12i/runs";
-export interface WebAgentClientOptions {
-    registry?: ParserRegistry;
-    fetchOptions?: FetchOptions;
-    reuseBrowser?: boolean;
-    search?: SearchProvider | SearchConfig | null;
-    fetchCache?: FetchCache;
-    snapshotStore?: SnapshotStore;
-    runStore?: RunStore;
-    extractionAdapter?: ExtractionAdapter;
-    /** When true, client owns and closes default in-memory stores it created. */
-    ownsDefaultStores?: boolean;
+import { type StoredIdentity } from "./identity.js";
+import { type RankedPackage } from "./rank.js";
+import { type UsageFields } from "./protocol.js";
+export declare const SDK_VERSION: string;
+/** Catalog service. Override with X12I_SDK_URL. */
+export declare const DEFAULT_SERVICE_URL = "https://x12i-sdk.x12i.com";
+export declare class SdkError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status?: number, code?: string);
 }
-export interface FetchSearchResultsOptions {
-    positions?: number[];
-    urls?: string[];
-    concurrency?: number;
-    continueOnError?: boolean;
-    fetchOptions?: FetchOptions;
-    signal?: AbortSignal;
+export type SearchResult = {
+    source: "service" | "registry";
+    ranked: boolean;
+    task: string;
+    results: RankedPackage[];
+};
+export type ReviewInput = {
+    package: string;
+    packageVersion: string;
+    agent: UsageFields["agent"];
+    outcome: UsageFields["outcome"];
+    rating: number;
+    worked?: string;
+    failed?: string;
+    needed?: string;
+    improve?: string;
+};
+export type ReportInput = Omit<ReviewInput, "rating">;
+export type ClientOptions = {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    identityPath?: string;
+};
+export type ReadmeStatus = "missing" | "stale" | "fresh";
+export type CachedPackage = {
+    readme: string;
+    readmeStatus: ReadmeStatus;
+    version: string | null;
+    description: string;
+    modifiedAt: string | null;
+    refreshedAt: string | null;
+};
+export type PackageView = {
+    name: string;
+    readme: string;
+    readmeStatus: ReadmeStatus;
+    version: string | null;
+    description: string;
+    modifiedAt: string | null;
+    refreshedAt: string | null;
+    updated: boolean;
+    source: "service" | "registry";
+    cached: CachedPackage;
+    detail: Record<string, unknown>;
+    refreshError?: string;
+};
+export declare class X12iClient {
+    readonly baseUrl: string;
+    readonly identityPath: string;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    search(task: string): Promise<SearchResult>;
+    catalog(cursor?: string, limit?: number): Promise<unknown>;
+    package(name: string): Promise<PackageView>;
+    readme(name: string): Promise<PackageView>;
+    reviews(name: string): Promise<unknown>;
+    report(input: ReportInput): Promise<unknown>;
+    review(input: ReviewInput): Promise<unknown>;
+    status(): Promise<unknown>;
+    ensureEnrolled(): Promise<StoredIdentity>;
+    private signedPost;
+    private readThrough;
+    private readmeFromRegistry;
+    private send;
 }
-export interface FetchedSearchPage {
-    position?: number;
-    url: string;
-    title?: string;
-    fetch?: FetchResult;
-    error?: string;
-}
-export interface SearchAndFetchRequest extends WebSearchRequest {
-    top?: number;
-    positions?: number[];
-    urls?: string[];
-    concurrency?: number;
-    continueOnError?: boolean;
-    fetchOptions?: FetchOptions;
-    signal?: AbortSignal;
-}
-export interface SearchAndFetchResult {
-    search: WebSearchResponse;
-    pages: FetchedSearchPage[];
-}
-/**
- * Canonical programmatic surface: fetch/retrieve/research/crawl/extract/runs.
- * CLI, REST, and MCP are thin adapters around this client.
- */
-export declare class WebAgentClient {
-    readonly registry: ParserRegistry;
-    private readonly defaultFetchOptions;
-    private readonly reuseBrowser;
-    private readonly searchProvider;
-    private browserPromise;
-    readonly fetchCache: FetchCache;
-    readonly snapshotStore: SnapshotStore;
-    readonly runStore: RunStore;
-    private readonly extractionAdapter?;
-    private readonly ownsCache;
-    private readonly ownsSnapshots;
-    private readonly ownsRuns;
-    constructor(options?: WebAgentClientOptions);
-    use<T>(parser: Parser<T>): this;
-    /** Download a URL via Playwright (compatibility default: browser strategy). */
-    fetch(url: string, options?: FetchOptions): Promise<FetchResult>;
-    /** Strategy-aware multi-format retrieval (default strategy: auto). */
-    retrieve(url: string, options?: RetrieveOptions): Promise<FetchResult>;
-    fetchBatch(request: {
-        urls: string[];
-        concurrency?: number;
-        continueOnError?: boolean;
-        retrieveOptions?: RetrieveOptions;
-        signal?: AbortSignal;
-    }): Promise<RetrieveBatchItem[]>;
-    retrieveCached(url: string, options?: CachedRetrieveOptions): Promise<FetchResult>;
-    classify(url: string, options?: FetchOptions): Promise<ClassifyCandidate[]>;
-    parse<T = unknown>(url: string, options?: FetchOptions): Promise<ParsedResult<T>>;
-    parseAs<T = unknown>(type: string, url: string, options?: FetchOptions): Promise<ParsedResult<T>>;
-    listParsers(): {
-        type: string;
-        description?: string;
-        version?: string;
-    }[];
-    ingest(rootUrl: string, options?: IngestOptions): Promise<IngestResult>;
-    search(request: WebSearchRequest, options?: {
-        signal?: AbortSignal;
-    }): Promise<WebSearchResponse>;
-    searchConfigured(): boolean;
-    fetchSearchResults(searchResult: WebSearchResponse, options?: FetchSearchResultsOptions): Promise<FetchedSearchPage[]>;
-    searchAndFetch(request: SearchAndFetchRequest): Promise<SearchAndFetchResult>;
-    research(request: ResearchRequest, options?: {
-        signal?: AbortSignal;
-    }): Promise<ResearchPacket>;
-    startResearch(request: ResearchRequest, opts?: {
-        idempotencyKey?: string;
-    }): Promise<RunRecord>;
-    private runResearchJob;
-    crawl(request: CrawlRequest, options?: {
-        signal?: AbortSignal;
-    }): Promise<CrawlResult>;
-    startCrawl(request: CrawlRequest, opts?: {
-        idempotencyKey?: string;
-    }): Promise<RunRecord>;
-    private runCrawlJob;
-    extract(request: ExtractRequest): Promise<ExtractResult>;
-    checkChanges(request: ChangeCheckRequest & {
-        url?: string;
-    }): Promise<ChangeCheckResult>;
-    getRun(runId: string): Promise<RunRecord | undefined>;
-    listRunItems(runId: string, options?: ListItemsOptions): Promise<ListItemsResult>;
-    cancelRun(runId: string): Promise<RunRecord>;
-    resumeRun(runId: string): Promise<RunRecord>;
-    private getBrowser;
-    close(): Promise<void>;
-}
-//# sourceMappingURL=client.d.ts.map