@agent-receipts/schema 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,479 @@
+import { z } from 'zod';
+
+declare const ReceiptStatus: z.ZodEnum<["pending", "completed", "failed", "timeout"]>;
+type ReceiptStatus = z.infer<typeof ReceiptStatus>;
+declare const ReceiptType: z.ZodEnum<["action", "verification", "judgment", "arbitration"]>;
+type ReceiptType = z.infer<typeof ReceiptType>;
+declare const Environment: z.ZodEnum<["production", "staging", "test"]>;
+type Environment = z.infer<typeof Environment>;
+declare const ErrorCode: z.ZodEnum<["UNAUTHORIZED", "KEY_REVOKED", "FORBIDDEN", "RECEIPT_NOT_FOUND", "CHAIN_NOT_FOUND", "AGENT_NOT_FOUND", "RECEIPT_NOT_PENDING", "RECEIPT_IMMUTABLE", "RATE_LIMIT_EXCEEDED", "VALIDATION_ERROR", "INTERNAL_ERROR"]>;
+type ErrorCode = z.infer<typeof ErrorCode>;
+
+/**
+ * The 12 fields that are cryptographically signed.
+ * These fields are extracted from a receipt and serialized as canonical JSON
+ * before signing with Ed25519.
+ */
+declare const SignablePayload: z.ZodObject<{
+    receipt_id: z.ZodString;
+    chain_id: z.ZodString;
+    receipt_type: z.ZodEnum<["action", "verification", "judgment", "arbitration"]>;
+    agent_id: z.ZodString;
+    org_id: z.ZodString;
+    action: z.ZodString;
+    input_hash: z.ZodString;
+    output_hash: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<["pending", "completed", "failed", "timeout"]>;
+    timestamp: z.ZodString;
+    completed_at: z.ZodNullable<z.ZodString>;
+    environment: z.ZodEnum<["production", "staging", "test"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "completed" | "failed" | "timeout";
+    action: string;
+    receipt_id: string;
+    chain_id: string;
+    receipt_type: "action" | "verification" | "judgment" | "arbitration";
+    agent_id: string;
+    org_id: string;
+    input_hash: string;
+    output_hash: string | null;
+    timestamp: string;
+    completed_at: string | null;
+    environment: "production" | "staging" | "test";
+}, {
+    status: "pending" | "completed" | "failed" | "timeout";
+    action: string;
+    receipt_id: string;
+    chain_id: string;
+    receipt_type: "action" | "verification" | "judgment" | "arbitration";
+    agent_id: string;
+    org_id: string;
+    input_hash: string;
+    output_hash: string | null;
+    timestamp: string;
+    completed_at: string | null;
+    environment: "production" | "staging" | "test";
+}>;
+type SignablePayload = z.infer<typeof SignablePayload>;
+/**
+ * The complete receipt object as returned by the API.
+ */
+declare const ActionReceipt: z.ZodObject<{
+    receipt_id: z.ZodString;
+    parent_receipt_id: z.ZodNullable<z.ZodString>;
+    chain_id: z.ZodString;
+    receipt_type: z.ZodEnum<["action", "verification", "judgment", "arbitration"]>;
+    agent_id: z.ZodString;
+    org_id: z.ZodString;
+    action: z.ZodString;
+    input_hash: z.ZodString;
+    output_hash: z.ZodNullable<z.ZodString>;
+    output_summary: z.ZodNullable<z.ZodString>;
+    model: z.ZodNullable<z.ZodString>;
+    tokens_in: z.ZodNullable<z.ZodNumber>;
+    tokens_out: z.ZodNullable<z.ZodNumber>;
+    cost_usd: z.ZodNullable<z.ZodNumber>;
+    latency_ms: z.ZodNullable<z.ZodNumber>;
+    tool_calls: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
+    timestamp: z.ZodString;
+    completed_at: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<["pending", "completed", "failed", "timeout"]>;
+    error: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    environment: z.ZodEnum<["production", "staging", "test"]>;
+    tags: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
+    constraints: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    constraint_result: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    signature: z.ZodString;
+    verify_url: z.ZodString;
+    callback_verified: z.ZodNullable<z.ZodBoolean>;
+    confidence: z.ZodNullable<z.ZodNumber>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "completed" | "failed" | "timeout";
+    action: string;
+    receipt_id: string;
+    chain_id: string;
+    receipt_type: "action" | "verification" | "judgment" | "arbitration";
+    agent_id: string;
+    org_id: string;
+    input_hash: string;
+    output_hash: string | null;
+    timestamp: string;
+    completed_at: string | null;
+    environment: "production" | "staging" | "test";
+    parent_receipt_id: string | null;
+    output_summary: string | null;
+    model: string | null;
+    tokens_in: number | null;
+    tokens_out: number | null;
+    cost_usd: number | null;
+    latency_ms: number | null;
+    tool_calls: string[] | null;
+    error: Record<string, unknown> | null;
+    tags: string[] | null;
+    constraints: Record<string, unknown> | null;
+    constraint_result: Record<string, unknown> | null;
+    signature: string;
+    verify_url: string;
+    callback_verified: boolean | null;
+    confidence: number | null;
+    metadata: Record<string, unknown>;
+}, {
+    status: "pending" | "completed" | "failed" | "timeout";
+    action: string;
+    receipt_id: string;
+    chain_id: string;
+    receipt_type: "action" | "verification" | "judgment" | "arbitration";
+    agent_id: string;
+    org_id: string;
+    input_hash: string;
+    output_hash: string | null;
+    timestamp: string;
+    completed_at: string | null;
+    environment: "production" | "staging" | "test";
+    parent_receipt_id: string | null;
+    output_summary: string | null;
+    model: string | null;
+    tokens_in: number | null;
+    tokens_out: number | null;
+    cost_usd: number | null;
+    latency_ms: number | null;
+    tool_calls: string[] | null;
+    error: Record<string, unknown> | null;
+    tags: string[] | null;
+    constraints: Record<string, unknown> | null;
+    constraint_result: Record<string, unknown> | null;
+    signature: string;
+    verify_url: string;
+    callback_verified: boolean | null;
+    confidence: number | null;
+    metadata: Record<string, unknown>;
+}>;
+type ActionReceipt = z.infer<typeof ActionReceipt>;
+
+/**
+ * What the client sends to POST /api/v1/receipts.
+ */
+declare const CreateReceiptInput: z.ZodObject<{
+    agent_id: z.ZodString;
+    action: z.ZodString;
+    input_hash: z.ZodString;
+    receipt_type: z.ZodDefault<z.ZodEnum<["action", "verification", "judgment", "arbitration"]>>;
+    status: z.ZodDefault<z.ZodEnum<["pending", "completed", "failed", "timeout"]>>;
+    environment: z.ZodDefault<z.ZodEnum<["production", "staging", "test"]>>;
+    parent_receipt_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    output_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    output_summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tokens_in: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tokens_out: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cost_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    latency_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tool_calls: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    tags: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    callback_verified: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "completed" | "failed" | "timeout";
+    action: string;
+    receipt_type: "action" | "verification" | "judgment" | "arbitration";
+    agent_id: string;
+    input_hash: string;
+    environment: "production" | "staging" | "test";
+    output_hash?: string | null | undefined;
+    parent_receipt_id?: string | null | undefined;
+    output_summary?: string | null | undefined;
+    model?: string | null | undefined;
+    tokens_in?: number | null | undefined;
+    tokens_out?: number | null | undefined;
+    cost_usd?: number | null | undefined;
+    latency_ms?: number | null | undefined;
+    tool_calls?: string[] | null | undefined;
+    tags?: string[] | null | undefined;
+    callback_verified?: boolean | null | undefined;
+    confidence?: number | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    action: string;
+    agent_id: string;
+    input_hash: string;
+    status?: "pending" | "completed" | "failed" | "timeout" | undefined;
+    receipt_type?: "action" | "verification" | "judgment" | "arbitration" | undefined;
+    output_hash?: string | null | undefined;
+    environment?: "production" | "staging" | "test" | undefined;
+    parent_receipt_id?: string | null | undefined;
+    output_summary?: string | null | undefined;
+    model?: string | null | undefined;
+    tokens_in?: number | null | undefined;
+    tokens_out?: number | null | undefined;
+    cost_usd?: number | null | undefined;
+    latency_ms?: number | null | undefined;
+    tool_calls?: string[] | null | undefined;
+    tags?: string[] | null | undefined;
+    callback_verified?: boolean | null | undefined;
+    confidence?: number | null | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+type CreateReceiptInput = z.infer<typeof CreateReceiptInput>;
+/**
+ * What the client sends to PATCH /api/v1/receipts/:id/complete.
+ */
+declare const CompleteReceiptInput: z.ZodObject<{
+    status: z.ZodEnum<["completed", "failed", "timeout"]>;
+    output_hash: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    output_summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tokens_in: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tokens_out: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cost_usd: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    latency_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tool_calls: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    callback_verified: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, "strip", z.ZodTypeAny, {
+    status: "completed" | "failed" | "timeout";
+    output_hash?: string | null | undefined;
+    output_summary?: string | null | undefined;
+    model?: string | null | undefined;
+    tokens_in?: number | null | undefined;
+    tokens_out?: number | null | undefined;
+    cost_usd?: number | null | undefined;
+    latency_ms?: number | null | undefined;
+    tool_calls?: string[] | null | undefined;
+    error?: Record<string, unknown> | null | undefined;
+    callback_verified?: boolean | null | undefined;
+    confidence?: number | null | undefined;
+}, {
+    status: "completed" | "failed" | "timeout";
+    output_hash?: string | null | undefined;
+    output_summary?: string | null | undefined;
+    model?: string | null | undefined;
+    tokens_in?: number | null | undefined;
+    tokens_out?: number | null | undefined;
+    cost_usd?: number | null | undefined;
+    latency_ms?: number | null | undefined;
+    tool_calls?: string[] | null | undefined;
+    error?: Record<string, unknown> | null | undefined;
+    callback_verified?: boolean | null | undefined;
+    confidence?: number | null | undefined;
+}>;
+type CompleteReceiptInput = z.infer<typeof CompleteReceiptInput>;
+/**
+ * What GET /api/v1/verify/:id returns.
+ * Note: Does NOT include org_id, metadata, tags, or output_summary (org-private).
+ */
+declare const VerifyResponse: z.ZodObject<{
+    verified: z.ZodBoolean;
+    receipt: z.ZodObject<{
+        receipt_id: z.ZodString;
+        chain_id: z.ZodString;
+        receipt_type: z.ZodEnum<["action", "verification", "judgment", "arbitration"]>;
+        agent_id: z.ZodString;
+        action: z.ZodString;
+        status: z.ZodEnum<["pending", "completed", "failed", "timeout"]>;
+        input_hash: z.ZodString;
+        output_hash: z.ZodNullable<z.ZodString>;
+        signature: z.ZodString;
+        timestamp: z.ZodString;
+        completed_at: z.ZodNullable<z.ZodString>;
+        environment: z.ZodEnum<["production", "staging", "test"]>;
+        latency_ms: z.ZodNullable<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "completed" | "failed" | "timeout";
+        action: string;
+        receipt_id: string;
+        chain_id: string;
+        receipt_type: "action" | "verification" | "judgment" | "arbitration";
+        agent_id: string;
+        input_hash: string;
+        output_hash: string | null;
+        timestamp: string;
+        completed_at: string | null;
+        environment: "production" | "staging" | "test";
+        latency_ms: number | null;
+        signature: string;
+    }, {
+        status: "pending" | "completed" | "failed" | "timeout";
+        action: string;
+        receipt_id: string;
+        chain_id: string;
+        receipt_type: "action" | "verification" | "judgment" | "arbitration";
+        agent_id: string;
+        input_hash: string;
+        output_hash: string | null;
+        timestamp: string;
+        completed_at: string | null;
+        environment: "production" | "staging" | "test";
+        latency_ms: number | null;
+        signature: string;
+    }>;
+    signature_valid: z.ZodBoolean;
+    chain_length: z.ZodNumber;
+    public_key_url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    verified: boolean;
+    receipt: {
+        status: "pending" | "completed" | "failed" | "timeout";
+        action: string;
+        receipt_id: string;
+        chain_id: string;
+        receipt_type: "action" | "verification" | "judgment" | "arbitration";
+        agent_id: string;
+        input_hash: string;
+        output_hash: string | null;
+        timestamp: string;
+        completed_at: string | null;
+        environment: "production" | "staging" | "test";
+        latency_ms: number | null;
+        signature: string;
+    };
+    signature_valid: boolean;
+    chain_length: number;
+    public_key_url: string;
+}, {
+    verified: boolean;
+    receipt: {
+        status: "pending" | "completed" | "failed" | "timeout";
+        action: string;
+        receipt_id: string;
+        chain_id: string;
+        receipt_type: "action" | "verification" | "judgment" | "arbitration";
+        agent_id: string;
+        input_hash: string;
+        output_hash: string | null;
+        timestamp: string;
+        completed_at: string | null;
+        environment: "production" | "staging" | "test";
+        latency_ms: number | null;
+        signature: string;
+    };
+    signature_valid: boolean;
+    chain_length: number;
+    public_key_url: string;
+}>;
+type VerifyResponse = z.infer<typeof VerifyResponse>;
+/**
+ * Query parameters for GET /api/v1/receipts.
+ */
+declare const ListReceiptsQuery: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    agent_id: z.ZodOptional<z.ZodString>;
+    action: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["pending", "completed", "failed", "timeout"]>>;
+    environment: z.ZodOptional<z.ZodEnum<["production", "staging", "test"]>>;
+    receipt_type: z.ZodOptional<z.ZodEnum<["action", "verification", "judgment", "arbitration"]>>;
+    chain_id: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    sort: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sort: string;
+    page: number;
+    limit: number;
+    status?: "pending" | "completed" | "failed" | "timeout" | undefined;
+    action?: string | undefined;
+    chain_id?: string | undefined;
+    receipt_type?: "action" | "verification" | "judgment" | "arbitration" | undefined;
+    agent_id?: string | undefined;
+    environment?: "production" | "staging" | "test" | undefined;
+    tag?: string | undefined;
+    from?: string | undefined;
+    to?: string | undefined;
+}, {
+    sort?: string | undefined;
+    status?: "pending" | "completed" | "failed" | "timeout" | undefined;
+    action?: string | undefined;
+    chain_id?: string | undefined;
+    receipt_type?: "action" | "verification" | "judgment" | "arbitration" | undefined;
+    agent_id?: string | undefined;
+    environment?: "production" | "staging" | "test" | undefined;
+    page?: number | undefined;
+    limit?: number | undefined;
+    tag?: string | undefined;
+    from?: string | undefined;
+    to?: string | undefined;
+}>;
+type ListReceiptsQuery = z.infer<typeof ListReceiptsQuery>;
+/**
+ * Pagination metadata included in list responses.
+ */
+declare const PaginationMeta: z.ZodObject<{
+    page: z.ZodNumber;
+    limit: z.ZodNumber;
+    total: z.ZodNumber;
+    total_pages: z.ZodNumber;
+    has_next: z.ZodBoolean;
+    has_prev: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    limit: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+}, {
+    page: number;
+    limit: number;
+    total: number;
+    total_pages: number;
+    has_next: boolean;
+    has_prev: boolean;
+}>;
+type PaginationMeta = z.infer<typeof PaginationMeta>;
+/**
+ * Standard error response format.
+ */
+declare const ErrorResponse: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodEnum<["UNAUTHORIZED", "KEY_REVOKED", "FORBIDDEN", "RECEIPT_NOT_FOUND", "CHAIN_NOT_FOUND", "AGENT_NOT_FOUND", "RECEIPT_NOT_PENDING", "RECEIPT_IMMUTABLE", "RATE_LIMIT_EXCEEDED", "VALIDATION_ERROR", "INTERNAL_ERROR"]>;
+        message: z.ZodString;
+        status: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        code: "UNAUTHORIZED" | "KEY_REVOKED" | "FORBIDDEN" | "RECEIPT_NOT_FOUND" | "CHAIN_NOT_FOUND" | "AGENT_NOT_FOUND" | "RECEIPT_NOT_PENDING" | "RECEIPT_IMMUTABLE" | "RATE_LIMIT_EXCEEDED" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        message: string;
+        status: number;
+    }, {
+        code: "UNAUTHORIZED" | "KEY_REVOKED" | "FORBIDDEN" | "RECEIPT_NOT_FOUND" | "CHAIN_NOT_FOUND" | "AGENT_NOT_FOUND" | "RECEIPT_NOT_PENDING" | "RECEIPT_IMMUTABLE" | "RATE_LIMIT_EXCEEDED" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        message: string;
+        status: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        code: "UNAUTHORIZED" | "KEY_REVOKED" | "FORBIDDEN" | "RECEIPT_NOT_FOUND" | "CHAIN_NOT_FOUND" | "AGENT_NOT_FOUND" | "RECEIPT_NOT_PENDING" | "RECEIPT_IMMUTABLE" | "RATE_LIMIT_EXCEEDED" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        message: string;
+        status: number;
+    };
+}, {
+    error: {
+        code: "UNAUTHORIZED" | "KEY_REVOKED" | "FORBIDDEN" | "RECEIPT_NOT_FOUND" | "CHAIN_NOT_FOUND" | "AGENT_NOT_FOUND" | "RECEIPT_NOT_PENDING" | "RECEIPT_IMMUTABLE" | "RATE_LIMIT_EXCEEDED" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        message: string;
+        status: number;
+    };
+}>;
+type ErrorResponse = z.infer<typeof ErrorResponse>;
+
+/**
+ * Validate data against a Zod schema.
+ * Returns { success: true, data } or { success: false, error: ErrorResponse }
+ */
+declare function validate<T extends z.ZodSchema>(schema: T, data: unknown): {
+    success: true;
+    data: z.infer<T>;
+} | {
+    success: false;
+    error: ErrorResponse;
+};
+/**
+ * Format Zod errors into a human-readable message.
+ */
+declare function formatZodError(error: z.ZodError): string;
+/**
+ * Create a standard error response object.
+ */
+declare function createErrorResponse(code: string, message: string, status: number): ErrorResponse;
+
+export { ActionReceipt, CompleteReceiptInput, CreateReceiptInput, Environment, Environment as EnvironmentType, ErrorCode, ErrorCode as ErrorCodeType, ErrorResponse, ListReceiptsQuery, PaginationMeta, ReceiptStatus, ReceiptStatus as ReceiptStatusType, ReceiptType, ReceiptType as ReceiptTypeType, SignablePayload, VerifyResponse, createErrorResponse, formatZodError, validate };