@perrylink/dsh-einvoice 0.0.0-stage → 0.1.0-alpha.1

package/lib/plugin/storage.d.ts

@@ -0,0 +1,212 @@
+/** Storage domain and local original-file store for SKU-04 S1. */
+import { z } from 'zod';
+import type { Context } from '@deepseek-ai/cordis';
+import { type InvoiceLine } from '../core/invoice.js';
+export declare const partySchema: z.ZodObject<{
+    name: z.ZodString;
+    tax_id: z.ZodString;
+}, z.core.$strip>;
+export declare const lineSchema: z.ZodObject<{
+    line_no: z.ZodNumber;
+    description: z.ZodString;
+    quantity: z.ZodOptional<z.ZodString>;
+    unit_price_cents: z.ZodOptional<z.ZodNumber>;
+    amount_cents: z.ZodNumber;
+    tax_rate: z.ZodOptional<z.ZodString>;
+    tax_cents: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const verificationSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        verified: "verified";
+        pending: "pending";
+        failed: "failed";
+        manual: "manual";
+    }>;
+    queued_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    attempts: z.ZodDefault<z.ZodNumber>;
+    last_result: z.ZodOptional<z.ZodString>;
+    manual_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const receiptSchema: z.ZodObject<{
+    receipt_id: z.ZodString;
+    result_code: z.ZodString;
+    result: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        unknown: "unknown";
+    }>;
+    verified_at: z.ZodString;
+    operator: z.ZodString;
+    receipt_sha256: z.ZodString;
+    receipt_path: z.ZodString;
+    recorded_at: z.ZodString;
+}, z.core.$strip>;
+export declare const invoiceSchema: z.ZodObject<{
+    doc_id: z.ZodString;
+    entity_id: z.ZodString;
+    invoice_no: z.ZodString;
+    invoice_code: z.ZodOptional<z.ZodString>;
+    issue_date: z.ZodString;
+    buyer: z.ZodObject<{
+        name: z.ZodString;
+        tax_id: z.ZodString;
+    }, z.core.$strip>;
+    seller: z.ZodObject<{
+        name: z.ZodString;
+        tax_id: z.ZodString;
+    }, z.core.$strip>;
+    amount_cents: z.ZodNumber;
+    tax_cents: z.ZodNumber;
+    total_cents: z.ZodNumber;
+    currency: z.ZodLiteral<"CNY">;
+    lines: z.ZodArray<z.ZodObject<{
+        line_no: z.ZodNumber;
+        description: z.ZodString;
+        quantity: z.ZodOptional<z.ZodString>;
+        unit_price_cents: z.ZodOptional<z.ZodNumber>;
+        amount_cents: z.ZodNumber;
+        tax_rate: z.ZodOptional<z.ZodString>;
+        tax_cents: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    confidence: z.ZodNumber;
+    field_evidence: z.ZodRecord<z.ZodString, z.ZodString>;
+    unknown_fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    parser_version: z.ZodString;
+    lifecycle: z.ZodEnum<{
+        received: "received";
+        parsed: "parsed";
+        verified: "verified";
+        archived: "archived";
+        quarantined: "quarantined";
+    }>;
+    verification: z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<{
+            verified: "verified";
+            pending: "pending";
+            failed: "failed";
+            manual: "manual";
+        }>;
+        queued_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<z.ZodString>;
+        attempts: z.ZodDefault<z.ZodNumber>;
+        last_result: z.ZodOptional<z.ZodString>;
+        manual_reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    receipts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        receipt_id: z.ZodString;
+        result_code: z.ZodString;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            unknown: "unknown";
+        }>;
+        verified_at: z.ZodString;
+        operator: z.ZodString;
+        receipt_sha256: z.ZodString;
+        receipt_path: z.ZodString;
+        recorded_at: z.ZodString;
+    }, z.core.$strip>>>;
+    source_path: z.ZodString;
+    source_sha256: z.ZodString;
+    source_size: z.ZodNumber;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    run_id: z.ZodString;
+    actor: z.ZodString;
+    evidence_sha256: z.ZodString;
+}, z.core.$strip>;
+export type InvoiceRecord = z.infer<typeof invoiceSchema>;
+export type InvoiceTable = {
+    get(key: string): InvoiceRecord | undefined;
+    entries(): IterableIterator<[string, InvoiceRecord]>;
+    keys(): IterableIterator<string>;
+    readonly size: number;
+    put(key: string, value: InvoiceRecord): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    update(key: string, fn: (current: InvoiceRecord) => InvoiceRecord): Promise<InvoiceRecord>;
+};
+export declare const finInvoiceSpec: {
+    name: string;
+    version: number;
+    tables: {
+        invoices: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, {
+            doc_id: string;
+            entity_id: string;
+            invoice_no: string;
+            issue_date: string;
+            buyer: {
+                name: string;
+                tax_id: string;
+            };
+            seller: {
+                name: string;
+                tax_id: string;
+            };
+            amount_cents: number;
+            tax_cents: number;
+            total_cents: number;
+            currency: "CNY";
+            lines: {
+                line_no: number;
+                description: string;
+                amount_cents: number;
+                quantity?: string | undefined;
+                unit_price_cents?: number | undefined;
+                tax_rate?: string | undefined;
+                tax_cents?: number | undefined;
+            }[];
+            confidence: number;
+            field_evidence: Record<string, string>;
+            unknown_fields: Record<string, unknown>;
+            parser_version: string;
+            lifecycle: "received" | "parsed" | "verified" | "archived" | "quarantined";
+            source_path: string;
+            source_sha256: string;
+            source_size: number;
+            created_at: string;
+            updated_at: string;
+            run_id: string;
+            actor: string;
+            evidence_sha256: string;
+            invoice_code?: string | undefined;
+            verification?: {
+                state: "verified" | "pending" | "failed" | "manual";
+                attempts: number;
+                queued_at?: string | undefined;
+                updated_at?: string | undefined;
+                last_result?: string | undefined;
+                manual_reason?: string | undefined;
+            } | undefined;
+            receipts?: {
+                receipt_id: string;
+                result_code: string;
+                result: "pass" | "fail" | "unknown";
+                verified_at: string;
+                operator: string;
+                receipt_sha256: string;
+                receipt_path: string;
+                recorded_at: string;
+            }[] | undefined;
+        }>;
+    };
+};
+export declare function openInvoiceTable(ctx: Context): Promise<InvoiceTable>;
+/** Generate a ULID-compatible 26-character document id. */
+export declare function newDocId(now?: number): string;
+export declare function sha256Buffer(buffer: Buffer): string;
+export declare function sha256File(filePath: string): Promise<string>;
+export declare function storeOriginal(baseDir: string, sha256: string, extension: string, buffer: Buffer): Promise<string>;
+export declare function findBySha(table: InvoiceTable, sha256: string): InvoiceRecord | undefined;
+export declare function findByInvoiceNo(table: InvoiceTable, entityId: string, invoiceNo: string): InvoiceRecord | undefined;
+export declare function assertUniqueInvoice(table: InvoiceTable, entityId: string, invoiceNo: string, docId: string): void;
+export declare function emptyInvoiceRecord(input: {
+    docId: string;
+    entityId: string;
+    sourcePath: string;
+    sha256: string;
+    size: number;
+    runId: string;
+    actor: string;
+}): InvoiceRecord;
+export declare function recordLines(lines: InvoiceLine[]): InvoiceLine[];

package/lib/plugin/storage.js

@@ -0,0 +1,188 @@
+/** Storage domain and local original-file store for SKU-04 S1. */
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { InvoiceError } from '../core/invoice.js';
+export const partySchema = z.object({
+    name: z.string(),
+    tax_id: z.string(),
+});
+export const lineSchema = z.object({
+    line_no: z.number().int().nonnegative(),
+    description: z.string(),
+    quantity: z.string().optional(),
+    unit_price_cents: z.number().int().optional(),
+    amount_cents: z.number().int(),
+    tax_rate: z.string().optional(),
+    tax_cents: z.number().int().optional(),
+});
+export const verificationSchema = z.object({
+    state: z.enum(['pending', 'verified', 'failed', 'manual']),
+    queued_at: z.string().optional(),
+    updated_at: z.string().optional(),
+    attempts: z.number().int().nonnegative().default(0),
+    last_result: z.string().optional(),
+    manual_reason: z.string().optional(),
+});
+export const receiptSchema = z.object({
+    receipt_id: z.string(),
+    result_code: z.string(),
+    result: z.enum(['pass', 'fail', 'unknown']),
+    verified_at: z.string(),
+    operator: z.string(),
+    receipt_sha256: z.string(),
+    receipt_path: z.string(),
+    recorded_at: z.string(),
+});
+export const invoiceSchema = z.object({
+    doc_id: z.string().min(1),
+    entity_id: z.string(),
+    invoice_no: z.string(),
+    invoice_code: z.string().optional(),
+    issue_date: z.string(),
+    buyer: partySchema,
+    seller: partySchema,
+    amount_cents: z.number().int(),
+    tax_cents: z.number().int(),
+    total_cents: z.number().int(),
+    currency: z.literal('CNY'),
+    lines: z.array(lineSchema),
+    confidence: z.number(),
+    field_evidence: z.record(z.string(), z.string()),
+    unknown_fields: z.record(z.string(), z.unknown()),
+    parser_version: z.string(),
+    lifecycle: z.enum(['received', 'parsed', 'verified', 'archived', 'quarantined']),
+    verification: verificationSchema.optional(),
+    receipts: z.array(receiptSchema).optional(),
+    source_path: z.string(),
+    source_sha256: z.string(),
+    source_size: z.number().int().nonnegative(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    run_id: z.string(),
+    actor: z.string(),
+    evidence_sha256: z.string(),
+});
+export const finInvoiceSpec = defineDomain({
+    name: 'fin_invoice',
+    version: 1,
+    tables: {
+        invoices: domainTable(invoiceSchema),
+    },
+});
+export async function openInvoiceTable(ctx) {
+    const domain = await ctx.storageDomain.open(finInvoiceSpec);
+    ctx.effect(() => () => domain.close(), 'dsh-einvoice.domainClose');
+    return domain.table('invoices');
+}
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Generate a ULID-compatible 26-character document id. */
+export function newDocId(now = Date.now()) {
+    let time = now;
+    let timePart = '';
+    for (let index = 0; index < 10; index += 1) {
+        timePart = (CROCKFORD[time % 32] ?? '0') + timePart;
+        time = Math.floor(time / 32);
+    }
+    const bytes = randomBytes(16);
+    let buffer = 0;
+    let bits = 0;
+    let randomPart = '';
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5 && randomPart.length < 16) {
+            bits -= 5;
+            randomPart += CROCKFORD[(buffer >> bits) & 31] ?? '0';
+        }
+    }
+    return timePart + randomPart;
+}
+export function sha256Buffer(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+export async function sha256File(filePath) {
+    const hash = createHash('sha256');
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', resolve);
+    });
+    return hash.digest('hex');
+}
+export async function storeOriginal(baseDir, sha256, extension, buffer) {
+    const directory = path.join(baseDir, 'originals');
+    await mkdir(directory, { recursive: true });
+    const safeExtension = extension.replace(/[^a-z0-9.]/gi, '').slice(0, 8);
+    const target = path.join(directory, `${sha256}${safeExtension}`);
+    try {
+        await writeFile(target, buffer, { mode: 0o600, flag: 'wx' });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EEXIST')
+            throw new InvoiceError('E_INV_STORAGE_FAILED', `cannot store original: ${String(error)}`, { retryable: true });
+    }
+    return target;
+}
+export function findBySha(table, sha256) {
+    for (const [, record] of table.entries()) {
+        if (record.source_sha256 === sha256)
+            return record;
+    }
+    return undefined;
+}
+export function findByInvoiceNo(table, entityId, invoiceNo) {
+    for (const [, record] of table.entries()) {
+        if (record.entity_id === entityId && record.invoice_no === invoiceNo)
+            return record;
+    }
+    return undefined;
+}
+export function assertUniqueInvoice(table, entityId, invoiceNo, docId) {
+    if (!invoiceNo)
+        return;
+    const existing = findByInvoiceNo(table, entityId, invoiceNo);
+    if (existing && existing.doc_id !== docId) {
+        throw new InvoiceError('E_INV_DUP_CONFLICT', `invoice ${invoiceNo} already exists for entity ${entityId}`, {
+            needs_review: true,
+            details: { existing_doc_id: existing.doc_id },
+        });
+    }
+}
+export function emptyInvoiceRecord(input) {
+    const now = new Date().toISOString();
+    return {
+        doc_id: input.docId,
+        entity_id: input.entityId,
+        invoice_no: '',
+        issue_date: '',
+        buyer: { name: '', tax_id: '' },
+        seller: { name: '', tax_id: '' },
+        amount_cents: 0,
+        tax_cents: 0,
+        total_cents: 0,
+        currency: 'CNY',
+        lines: [],
+        confidence: 0,
+        field_evidence: {},
+        unknown_fields: {},
+        parser_version: '',
+        lifecycle: 'received',
+        source_path: input.sourcePath,
+        source_sha256: input.sha256,
+        source_size: input.size,
+        created_at: now,
+        updated_at: now,
+        run_id: input.runId,
+        actor: input.actor,
+        evidence_sha256: '',
+    };
+}
+export function recordLines(lines) {
+    return lines.map((line) => ({ ...line }));
+}

package/lib/plugin/tools.d.ts

@@ -0,0 +1,8 @@
+/** Three S1 model-facing tools: ingest, parse, query. */
+import { type InvoiceTable } from './storage.js';
+export interface ToolDeps {
+    table: InvoiceTable;
+    baseDir: string;
+    inputRoots: string[];
+}
+export declare function createTools(deps: ToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];