agentex-creator-sdk 1.0.0

package/dist/packages/sdk/src/errors.js

@@ -0,0 +1,24 @@
+export class AgentexApiError extends Error {
+    kind;
+    status;
+    code;
+    retryable;
+    retryAfterMs;
+    name = 'AgentexApiError';
+    constructor(kind, status, code, message, 
+    /** True when repeating the same call can succeed (network failures, 5xx other than 503, rate limits, timeouts). */
+    retryable, 
+    /** Server-suggested wait before retrying (from `Retry-After`), when one was sent. */
+    retryAfterMs = null) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.code = code;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+    }
+    /** Set when the failure happened after a run was accepted (`research()` waiting), so the caller can resume with `waitForRun(runId)`. */
+    runId;
+}
+/** Type guard for `catch (error)` blocks. */
+export function isAgentexApiError(error) { return error instanceof AgentexApiError; }

package/dist/packages/sdk/src/index.d.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+import { AgentManifestSchema, type AgentManifest } from '../../contracts/src/index.js';
+export { SDK_VERSION } from './version.js';
+export declare const MAX_CREATOR_JSON_BYTES = 65536;
+export declare const ScaffoldOptionsSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    chains: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        ethereum: "ethereum";
+        base: "base";
+    }>>>;
+    researchPolicy: z.ZodOptional<z.ZodObject<{
+        readOwner: z.ZodBoolean;
+        readProxySlots: z.ZodBoolean;
+    }, z.core.$strict>>;
+    limits: z.ZodOptional<z.ZodObject<{
+        maximumRpcCalls: z.ZodOptional<z.ZodNumber>;
+        maximumDurationMs: z.ZodOptional<z.ZodNumber>;
+        maximumOutputBytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    author: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ScaffoldOptions = z.infer<typeof ScaffoldOptionsSchema>;
+/** Reject executable/accessor/class values before schema parsing or JSON serialization can invoke them. */
+export declare function assertJsonData(raw: unknown): void;
+export declare function parseCreatorJson(text: string): unknown;
+/** Validation checks the actually executable subset, not just a structurally valid graph. */
+export declare function validateManifest(raw: unknown): AgentManifest;
+export declare function scaffoldTokenResearcher(raw: ScaffoldOptions): AgentManifest;
+export declare function estimateManifest(raw: unknown): {
+    kind: "bounded_rpc_plan";
+    manifestHash: string;
+    policy: Readonly<{
+        readOwner: boolean;
+        readProxySlots: boolean;
+    }>;
+    rpc: {
+        freshFinalized: {
+            nominalCalls: number;
+            fitsBudget: boolean;
+        };
+        explicitSnapshot: {
+            nominalCalls: number;
+            fitsBudget: boolean;
+        };
+        attemptRange: {
+            minimum: number;
+            maximum: number;
+        };
+        totalRunMaximum: number;
+    };
+    deadlineMs: number;
+    maximumOutputBytes: number;
+    modelTokens: number;
+    providerCost: {
+        status: "unpriced";
+        atomic: null;
+        currency: null;
+    };
+    limitations: string[];
+};
+/** Fixed platform fixtures run in process. No creator code, credentials, RPC URL or network transport is accepted. */
+export declare function testManifest(raw: unknown): Promise<import("../../publication/src/fixtures.js").EvaluationSnapshot>;
+export declare const CreatorPackageSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"agentex.creator-package.v1">;
+    manifest: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<"1.0">;
+        id: z.ZodString;
+        version: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        author: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            ownership: z.ZodEnum<{
+                "first-party": "first-party";
+                independent: "independent";
+            }>;
+        }, z.core.$strict>;
+        license: z.ZodString;
+        visibility: z.ZodEnum<{
+            private: "private";
+            "source-visible": "source-visible";
+            "source-private": "source-private";
+        }>;
+        chains: z.ZodArray<z.ZodEnum<{
+            ethereum: "ethereum";
+            base: "base";
+            robinhood: "robinhood";
+        }>>;
+        inputSchema: z.ZodObject<{
+            type: z.ZodLiteral<"object">;
+            properties: z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodEnum<{
+                    string: "string";
+                    number: "number";
+                    boolean: "boolean";
+                    array: "array";
+                    integer: "integer";
+                }>;
+                description: z.ZodString;
+                enum: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            }, z.core.$strict>>;
+            required: z.ZodArray<z.ZodString>;
+            additionalProperties: z.ZodLiteral<false>;
+        }, z.core.$strict>;
+        outputSchemaId: z.ZodEnum<{
+            "agentex.token-research.v1": "agentex.token-research.v1";
+            "agentex.transaction-inspection.v1": "agentex.transaction-inspection.v1";
+            "agentex.watchtower-window.v1": "agentex.watchtower-window.v1";
+        }>;
+        tools: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+            capability: z.ZodLiteral<"evm.read">;
+            chains: z.ZodArray<z.ZodEnum<{
+                ethereum: "ethereum";
+                base: "base";
+                robinhood: "robinhood";
+            }>>;
+            addressScope: z.ZodEnum<{
+                "input-address": "input-address";
+                "input-transaction": "input-transaction";
+                "input-watch-scope": "input-watch-scope";
+            }>;
+            maximumCalls: z.ZodNumber;
+        }, z.core.$strict>>;
+        modelPolicy: z.ZodObject<{
+            mode: z.ZodLiteral<"deterministic">;
+            maximumModelTokens: z.ZodLiteral<0>;
+        }, z.core.$strict>;
+        researchPolicy: z.ZodOptional<z.ZodObject<{
+            readOwner: z.ZodBoolean;
+            readProxySlots: z.ZodBoolean;
+        }, z.core.$strict>>;
+        policy: z.ZodOptional<z.ZodObject<{
+            analysis: z.ZodObject<{
+                mode: z.ZodLiteral<"summary">;
+                maximumOutputTokens: z.ZodNumber;
+                maximumCostMicrousd: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        marketPolicy: z.ZodOptional<z.ZodObject<{
+            discoverPools: z.ZodBoolean;
+            recentHolderActivity: z.ZodBoolean;
+        }, z.core.$strict>>;
+        limits: z.ZodObject<{
+            maximumRpcCalls: z.ZodNumber;
+            maximumDurationMs: z.ZodNumber;
+            maximumOutputBytes: z.ZodNumber;
+            maximumGraphDepth: z.ZodNumber;
+            maximumPages: z.ZodLiteral<0>;
+            maximumExecutionAtomic: z.ZodString;
+        }, z.core.$strict>;
+        workflow: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"input">;
+            id: z.ZodString;
+            dependsOn: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"tool">;
+            tool: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                source: z.ZodLiteral<"input">;
+                path: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                source: z.ZodLiteral<"node">;
+                nodeId: z.ZodString;
+                path: z.ZodString;
+            }, z.core.$strict>], "source">>;
+            id: z.ZodString;
+            dependsOn: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"condition">;
+            field: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                source: z.ZodLiteral<"input">;
+                path: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                source: z.ZodLiteral<"node">;
+                nodeId: z.ZodString;
+                path: z.ZodString;
+            }, z.core.$strict>], "source">;
+            operator: z.ZodEnum<{
+                equals: "equals";
+                exists: "exists";
+            }>;
+            value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodNumber]>>;
+            whenTrue: z.ZodString;
+            whenFalse: z.ZodString;
+            id: z.ZodString;
+            dependsOn: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"output">;
+            from: z.ZodString;
+            id: z.ZodString;
+            dependsOn: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>], "type">>;
+        testCases: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    manifestHash: z.ZodString;
+}, z.core.$strict>;
+export type CreatorPackage = z.infer<typeof CreatorPackageSchema>;
+export declare function parseCreatorPackage(raw: unknown): CreatorPackage;
+export declare function prepareCreatorPackage(raw: unknown): CreatorPackage;
+export declare const ImportKeySchema: z.ZodString;
+export interface CreatorImportRequest {
+    method: 'POST';
+    path: '/v1/packages/import';
+    body: {
+        package: CreatorPackage;
+        idempotencyKey: string;
+    };
+}
+/** Applications supply their authenticated transport; package JSON never supplies credentials or destinations. */
+export type CreatorImportTransport = (request: CreatorImportRequest) => Promise<unknown>;
+export declare function submitCreatorPackage(raw: unknown, options: {
+    idempotencyKey: string;
+    transport: CreatorImportTransport;
+}): Promise<{
+    status: "imported_for_testing";
+    notice: string;
+    draft: {
+        id: string;
+    };
+    version: {
+        id: string;
+        manifestHash: string;
+    };
+    sourceManifestHash: string;
+    recovered: boolean;
+}>;
+export { AgentManifestSchema };
+export type { AgentManifest };

package/dist/packages/sdk/src/index.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { AgentManifestSchema, ResearchPolicySchema, SupportedTokenResearcherManifestSchema, TOKEN_RESEARCHER_MANIFEST_V2, contentHash, getTokenResearcherRpcPlan, publishManifest } from '../../contracts/src/index.js';
+import { evaluateManifest } from '../../publication/src/fixtures.js';
+export { SDK_VERSION } from './version.js';
+export const MAX_CREATOR_JSON_BYTES = 65_536;
+const Identifier = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+const Hash = z.string().regex(/^[a-f0-9]{64}$/);
+function invalidData(message) { throw new z.ZodError([{ code: 'custom', path: [], message }]); }
+export const ScaffoldOptionsSchema = z.strictObject({
+    id: Identifier, name: z.string().trim().min(1).max(100), description: z.string().trim().min(1).max(2000).optional(),
+    chains: z.array(z.enum(['ethereum', 'base'])).min(1).max(2).refine(chains => new Set(chains).size === chains.length, 'Duplicate analysis chain').optional(),
+    researchPolicy: ResearchPolicySchema.optional(),
+    limits: z.strictObject({ maximumRpcCalls: z.number().int().min(1).max(16).optional(), maximumDurationMs: z.number().int().min(1000).max(60_000).optional(),
+        maximumOutputBytes: z.number().int().min(1024).max(131_072).optional() }).optional(),
+    author: z.strictObject({ id: Identifier, name: z.string().trim().min(1).max(100) }).optional(),
+});
+/** Reject executable/accessor/class values before schema parsing or JSON serialization can invoke them. */
+export function assertJsonData(raw) {
+    const ancestors = new Set();
+    let nodes = 0;
+    let stringBytes = 0;
+    function visit(value, depth) {
+        if (++nodes > 20_000 || depth > 32)
+            invalidData('Creator JSON exceeds the structural limit.');
+        if (typeof value === 'string') {
+            stringBytes += Buffer.byteLength(value);
+            if (stringBytes > MAX_CREATOR_JSON_BYTES)
+                invalidData('Creator JSON exceeds the byte limit.');
+            return;
+        }
+        if (value === null || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)))
+            return;
+        if (typeof value !== 'object')
+            invalidData('Only finite JSON data is accepted; executable values are unsupported.');
+        if (ancestors.has(value))
+            invalidData('Cyclic creator data is unsupported.');
+        if (Object.getOwnPropertySymbols(value).length)
+            invalidData('Symbol properties are unsupported.');
+        const array = Array.isArray(value);
+        if (!array && Object.getPrototypeOf(value) !== Object.prototype)
+            invalidData('Only plain JSON objects are supported.');
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (array && Object.keys(descriptors).length !== value.length + 1)
+            invalidData('Sparse arrays or custom array properties are unsupported.');
+        ancestors.add(value);
+        for (const [key, descriptor] of Object.entries(descriptors)) {
+            if (array && key === 'length')
+                continue;
+            if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value'))
+                invalidData('Accessors and hidden properties are unsupported.');
+            if (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))
+                invalidData('Custom array properties are unsupported.');
+            stringBytes += Buffer.byteLength(key);
+            if (stringBytes > MAX_CREATOR_JSON_BYTES)
+                invalidData('Creator JSON exceeds the byte limit.');
+            visit(descriptor.value, depth + 1);
+        }
+        ancestors.delete(value);
+    }
+    visit(raw, 0);
+    if (Buffer.byteLength(JSON.stringify(raw)) > MAX_CREATOR_JSON_BYTES)
+        invalidData('Creator JSON exceeds the byte limit.');
+}
+export function parseCreatorJson(text) {
+    if (Buffer.byteLength(text) > MAX_CREATOR_JSON_BYTES)
+        invalidData('Creator JSON exceeds the byte limit.');
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        invalidData('Input must contain one valid JSON value. JavaScript and module files are unsupported.');
+    }
+    assertJsonData(raw);
+    return raw;
+}
+/** Validation checks the actually executable subset, not just a structurally valid graph. */
+export function validateManifest(raw) {
+    assertJsonData(raw);
+    return publishManifest(SupportedTokenResearcherManifestSchema.parse(raw)).manifest;
+}
+export function scaffoldTokenResearcher(raw) {
+    assertJsonData(raw);
+    const options = ScaffoldOptionsSchema.parse(raw);
+    // New packages start from the current 0.2.0 template (instant-read wording); 0.1.0 packages still validate unchanged.
+    const manifest = structuredClone(TOKEN_RESEARCHER_MANIFEST_V2);
+    manifest.id = options.id;
+    manifest.name = options.name;
+    manifest.description = options.description ?? 'Inspect required ERC-20 metadata and selected owner/proxy controls at the latest block (sequencer-confirmed), rechecked at completion. Selected omissions are explicit; exhaustive authority, holder and market coverage is unavailable.';
+    manifest.author = { ...(options.author ?? { id: 'local-creator', name: 'Local creator' }), ownership: 'independent' };
+    manifest.visibility = 'private';
+    if (options.chains) {
+        manifest.chains = options.chains;
+        manifest.tools[0].chains = options.chains;
+        manifest.inputSchema.properties.chain.enum = options.chains;
+    }
+    if (options.researchPolicy)
+        manifest.researchPolicy = options.researchPolicy;
+    if (options.limits) {
+        Object.assign(manifest.limits, options.limits);
+        manifest.tools[0].maximumCalls = manifest.limits.maximumRpcCalls;
+    }
+    return validateManifest(manifest);
+}
+export function estimateManifest(raw) {
+    const manifest = validateManifest(raw);
+    const plan = getTokenResearcherRpcPlan(manifest);
+    return {
+        kind: 'bounded_rpc_plan', manifestHash: contentHash(manifest), policy: plan.policy,
+        rpc: { freshFinalized: { nominalCalls: plan.latestSnapshotCalls, fitsBudget: plan.latestSnapshotCalls <= plan.maximumRpcCalls },
+            explicitSnapshot: { nominalCalls: plan.explicitSnapshotCalls, fitsBudget: plan.explicitSnapshotCalls <= plan.maximumRpcCalls },
+            attemptRange: { minimum: 0, maximum: plan.maximumRpcCalls }, totalRunMaximum: plan.maximumRpcCalls },
+        deadlineMs: Math.min(60_000, manifest.limits.maximumDurationMs), maximumOutputBytes: Math.min(131_072, manifest.limits.maximumOutputBytes),
+        modelTokens: 0, providerCost: { status: 'unpriced', atomic: null, currency: null },
+        limitations: ['Nominal calls assume deployed code and all selected reads completing. Failure or cancellation can stop earlier.',
+            'Recovery adds fresh identity/header reads and must share the original persisted run budget; retries do not receive a new allowance.',
+            'This is an operation estimate, not a marketplace quote or a provider invoice. Actual price and payment authorization come from the server quote flow.',
+            'Omitting owner/proxy checks reduces observed coverage and does not establish absence of privileged controls.'],
+    };
+}
+/** Fixed platform fixtures run in process. No creator code, credentials, RPC URL or network transport is accepted. */
+export async function testManifest(raw) { return evaluateManifest(validateManifest(raw)); }
+export const CreatorPackageSchema = z.strictObject({ schemaVersion: z.literal('agentex.creator-package.v1'),
+    manifest: SupportedTokenResearcherManifestSchema, manifestHash: Hash,
+}).superRefine((envelope, ctx) => {
+    if (contentHash(envelope.manifest) !== envelope.manifestHash)
+        ctx.addIssue({ code: 'custom', path: ['manifestHash'], message: 'Package manifest hash does not match its JSON data.' });
+});
+export function parseCreatorPackage(raw) {
+    assertJsonData(raw);
+    const envelope = CreatorPackageSchema.parse(raw);
+    return Object.freeze({ ...envelope, manifest: validateManifest(envelope.manifest) });
+}
+export function prepareCreatorPackage(raw) {
+    const manifest = validateManifest(raw);
+    return parseCreatorPackage({ schemaVersion: 'agentex.creator-package.v1', manifest, manifestHash: contentHash(manifest) });
+}
+export const ImportKeySchema = z.string().min(8).max(128).regex(/^[A-Za-z0-9_-]+$/);
+const ImportResponseSchema = z.object({ draft: z.object({ id: z.uuid() }), version: z.object({ id: z.uuid(), manifestHash: Hash }), sourceManifestHash: Hash, recovered: z.boolean() });
+export async function submitCreatorPackage(raw, options) {
+    const envelope = parseCreatorPackage(raw);
+    const idempotencyKey = ImportKeySchema.parse(options.idempotencyKey);
+    const response = ImportResponseSchema.parse(await options.transport({ method: 'POST', path: '/v1/packages/import', body: { package: envelope, idempotencyKey } }));
+    if (response.sourceManifestHash !== envelope.manifestHash)
+        throw new Error('The import response does not match the submitted package hash.');
+    return { ...response, status: 'imported_for_testing',
+        notice: 'The server bound author identity and private visibility to the authenticated creator. Import is not evaluation, review approval, publication or a buyer purchase.' };
+}
+// Export the generic contract type for SDK users; unsupported manifests still fail validateManifest.
+export { AgentManifestSchema };

package/dist/packages/sdk/src/local.d.ts

@@ -0,0 +1,11 @@
+import { type CreatorImportTransport } from './index.js';
+export declare function readCreatorFile(file: string, workspace?: string): Promise<unknown>;
+/** Parents must already exist. wx rejects existing files, including a final-component symlink. */
+export declare function writeCreatorFile(file: string, value: unknown, workspace?: string): Promise<void>;
+export declare function loopbackOrigin(raw: string): string;
+/** Development SIWE session transport. Endpoint selection is never taken from package data. */
+export declare function createLocalImportTransport(options: {
+    api: string;
+    origin: string;
+    sessionToken: string;
+}): CreatorImportTransport;

package/dist/packages/sdk/src/local.js

@@ -0,0 +1,110 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath, writeFile } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+import { MAX_CREATOR_JSON_BYTES, parseCreatorJson } from './index.js';
+function inside(root, target) { const path = relative(root, target); return path !== '' && path !== '..' && !path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) && !isAbsolute(path); }
+async function jsonPath(file, workspace, existing) {
+    if (extname(file).toLowerCase() !== '.json' || file.includes('\0'))
+        throw new Error('A local .json file is required.');
+    const root = await realpath(workspace);
+    const target = resolve(workspace, file);
+    if (!inside(root, target))
+        throw new Error('The JSON file must remain inside the selected working directory.');
+    if (process.platform === 'win32' && relative(root, target).split(/[\\/]/).some(part => part.includes(':') || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)))
+        throw new Error('Windows device paths, alternate data streams and ambiguous path components are unsupported.');
+    const parent = await realpath(dirname(target));
+    if (parent !== root && !inside(root, parent))
+        throw new Error('The JSON parent directory escapes the working directory.');
+    if (existing) {
+        const stat = await lstat(target);
+        if (!stat.isFile() || stat.isSymbolicLink() || !inside(root, await realpath(target)))
+            throw new Error('Only regular JSON files inside the working directory are accepted.');
+    }
+    return target;
+}
+export async function readCreatorFile(file, workspace = process.cwd()) {
+    const target = await jsonPath(file, workspace, true);
+    const handle = await open(target, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > MAX_CREATOR_JSON_BYTES)
+            throw new Error('Creator JSON exceeds the regular-file or size limit.');
+        const buffer = Buffer.alloc(MAX_CREATOR_JSON_BYTES + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = await handle.read(buffer, length, buffer.length - length, null);
+            if (!read.bytesRead)
+                break;
+            length += read.bytesRead;
+        }
+        if (length > MAX_CREATOR_JSON_BYTES)
+            throw new Error('Creator JSON exceeds the byte limit.');
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, length));
+        return parseCreatorJson(text);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Parents must already exist. wx rejects existing files, including a final-component symlink. */
+export async function writeCreatorFile(file, value, workspace = process.cwd()) {
+    const target = await jsonPath(file, workspace, false);
+    const data = `${JSON.stringify(value, null, 2)}\n`;
+    if (Buffer.byteLength(data) > 2_097_152)
+        throw new Error('CLI output exceeds its file-size limit.');
+    await writeFile(target, data, { flag: 'wx', mode: 0o600 });
+}
+export function loopbackOrigin(raw) {
+    const url = new URL(raw);
+    if (raw !== raw.trim() || !['http:', 'https:'].includes(url.protocol) || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+        || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
+        throw new Error('An exact loopback HTTP(S) origin is required.');
+    return url.origin;
+}
+/** Development SIWE session transport. Endpoint selection is never taken from package data. */
+export function createLocalImportTransport(options) {
+    const api = loopbackOrigin(options.api);
+    const origin = loopbackOrigin(options.origin);
+    if (!/^[a-f0-9]{64}$/.test(options.sessionToken))
+        throw new Error('A valid development session token is required.');
+    return async (request) => {
+        if (request.path !== '/v1/packages/import' || request.method !== 'POST')
+            throw new Error('Only the creator import endpoint is supported.');
+        const response = await fetch(`${api}${request.path}`, { method: 'POST', headers: { 'content-type': 'application/json', origin,
+                cookie: `agentex_session=${options.sessionToken}` }, body: JSON.stringify(request.body), redirect: 'error', signal: AbortSignal.timeout(10_000) });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Creator import rejected with HTTP ${response.status}.`);
+        }
+        if (!/^application\/json(?:;|$)/i.test(response.headers.get('content-type') ?? '') || Number(response.headers.get('content-length') ?? 0) > 131_072) {
+            await response.body?.cancel();
+            throw new Error('Creator import response has an unsupported type or size.');
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error('Creator import response is empty.');
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > 131_072)
+                    throw new Error('Creator import response exceeds its byte limit.');
+                chunks.push(value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+        try {
+            return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        }
+        catch {
+            throw new Error('Creator import response is not valid JSON.');
+        }
+    };
+}

package/dist/packages/sdk/src/rails.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Payment rails and asset ids. AGENTEX names every payment asset with a ledger asset id:
+ *
+ * - `solana:mainnet-beta/native`: SOL on Solana (9 decimals). The default rail.
+ * - `solana:mainnet-beta/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`: USDC on Solana (6 decimals).
+ * - `eip155:4663/native`: ETH on Robinhood Chain (18 decimals).
+ *
+ * One listing can accept several rails. An API key is bound to one payment profile, and so to one asset: a SOL or USDC key belongs to a
+ * Solana account, an ETH key to an EVM account. These helpers are pure data; they never contact the network.
+ */
+export type BuyerProfile = 'sim' | 'local_custody' | 'solana_sol' | 'solana_usdc';
+export type PaymentRail = 'solana' | 'evm' | 'sim';
+export declare const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export declare const SOL_ASSET_ID = "solana:mainnet-beta/native";
+export declare const USDC_ASSET_ID = "solana:mainnet-beta/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export declare const ETH_ROBINHOOD_ASSET_ID = "eip155:4663/native";
+/** The production payment assets, SOL first. */
+export declare const ASSETS: Readonly<{
+    readonly SOL: "solana:mainnet-beta/native";
+    readonly USDC: "solana:mainnet-beta/spl:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    readonly ETH_ROBINHOOD: "eip155:4663/native";
+}>;
+/** SOL on Solana. */
+export declare const DEFAULT_ASSET_ID = "solana:mainnet-beta/native";
+/** Short names accepted wherever an asset id is (`sol`, `usdc`, `eth`). */
+export declare const ASSET_ALIASES: Readonly<Record<'sol' | 'usdc' | 'eth', string>>;
+export interface PaymentAsset {
+    assetId: string;
+    rail: PaymentRail;
+    /** The API key profile that pays in this asset. */
+    profile: BuyerProfile;
+    /** Solana cluster (`mainnet-beta`, `devnet`, `localnet`), the EVM chain id as text, or `local-sim`. */
+    network: string;
+    networkLabel: string;
+    /** `SOL`, `USDC`, `ETH` or `SIM`. An unrecognised SPL mint or ERC-20 reads as `SPL` or `ERC-20` with unknown decimals. */
+    currency: string;
+    decimals: number | null;
+    mint: string | null;
+    chainId: number | null;
+    contract: string | null;
+    /** For example "SOL on Solana" or "ETH on Robinhood Chain". */
+    label: string;
+}
+/** Accepts an asset id or an alias (`sol`, `usdc`, `eth`) and returns the validated asset id. */
+export declare function resolveAssetId(value: string): string;
+/** Parses an asset id (or an alias) into its rail, network, currency and decimals. Throws `invalid_input` for anything else. */
+export declare function describeAsset(value: string): PaymentAsset;
+/** The API key profile that pays in an asset: SOL → `solana_sol`, USDC → `solana_usdc`, ETH → `local_custody`. */
+export declare function profileForAsset(assetId: string): BuyerProfile;
+/** The quote, acceptance, catalog and billing route prefix for a profile. The Solana rail serves SOL and USDC keys. */
+export declare function railPath(profile: BuyerProfile): '/v1/rehearsal' | '/v1/custody' | '/v1/solana-custody';
+/** The asset id of a ledger asset object, such as a quote's `asset` (`{ namespace: 'solana', cluster, kind, mint?, decimals }`). */
+export declare function assetIdOf(asset: unknown): string | null;
+/** Exact decimal text for an atomic amount: `formatAtomic('2200000', 9)` is `"0.0022"`. No floats, no rounding. */
+export declare function formatAtomic(amount: string | bigint, decimals: number): string;
+/** Exact atomic amount for a decimal text: `parseAmount('0.05', 9)` is `"50000000"`. Throws when the text has more precision than the asset. */
+export declare function parseAmount(value: string, decimals: number): string;
+/** "0.0022 SOL". Falls back to the atomic amount and asset id when the asset's decimals are unknown. */
+export declare function formatAmount(amount: string | bigint, asset: string | PaymentAsset): string;