@paprflare/tally 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,478 @@
+import { z } from 'zod';
+
+/**
+ * Tally's HTTP layer is not a reliable signal of success. A failed voucher
+ * import still comes back as HTTP 200 with a <LINEERROR> buried in the body.
+ * Network failures, XML parse failures, and Tally-side rejections are three
+ * different failure classes with three different recovery strategies (retry,
+ * fix-your-builder-bug, fix-your-data) — so we keep them as distinct codes
+ * instead of collapsing everything into a generic Error.
+ */
+type TallyErrorCode = "NETWORK_ERROR" | "TIMEOUT" | "PARSE_ERROR" | "TALLY_REJECTED" | "VALIDATION_ERROR" | "NOT_FOUND" | "UNKNOWN";
+interface TallyError {
+    code: TallyErrorCode;
+    message: string;
+    /** Raw <LINEERROR> text from Tally, when code === "TALLY_REJECTED" */
+    tallyMessage?: string;
+    /** The XML request body that produced this error, kept for debugging/logging */
+    requestXml?: string;
+    /** The raw XML response body, when one was received */
+    responseXml?: string;
+    /** Underlying cause (e.g. an AxiosError, a ZodError), for stack traces */
+    cause?: unknown;
+}
+type Result<T, E = TallyError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare function ok<T>(value: T): Result<T, never>;
+declare function err<E = TallyError>(error: E): Result<never, E>;
+declare function tallyError(code: TallyErrorCode, message: string, extra?: Partial<Omit<TallyError, "code" | "message">>): TallyError;
+/** Narrow a Result to its value, or throw — for callers who'd rather not
+ * thread Result through their own code. Named unwrap (not "get") so misuse
+ * is obvious at the call site. */
+declare function unwrap<T>(result: Result<T, TallyError>): T;
+interface TallyConfig {
+    host: string;
+    port: number;
+    /** Defaults to false; set true only for instances behind TLS termination */
+    https?: boolean;
+    /** Defaults to the active company in Tally if omitted */
+    company?: string;
+    /** Request timeout in ms; Tally can be slow on large COLLECTION exports */
+    timeoutMs?: number;
+    /** Retries on NETWORK_ERROR/TIMEOUT only — never on TALLY_REJECTED */
+    retries?: number;
+}
+
+declare const LedgerInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    group: z.ZodString;
+    gstin: z.ZodOptional<z.ZodString>;
+    openingBalance: z.ZodOptional<z.ZodNumber>;
+    openingBalanceType: z.ZodOptional<z.ZodEnum<{
+        Debit: "Debit";
+        Credit: "Credit";
+    }>>;
+    address: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    state: z.ZodOptional<z.ZodString>;
+    pincode: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LedgerInput = z.infer<typeof LedgerInputSchema>;
+declare const LedgerSchema: z.ZodObject<{
+    name: z.ZodString;
+    guid: z.ZodString;
+    group: z.ZodString;
+    gstin: z.ZodOptional<z.ZodString>;
+    closingBalance: z.ZodOptional<z.ZodNumber>;
+    state: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Ledger = z.infer<typeof LedgerSchema>;
+declare const StockItemSchema: z.ZodObject<{
+    name: z.ZodString;
+    guid: z.ZodString;
+    unit: z.ZodString;
+    closingQty: z.ZodOptional<z.ZodNumber>;
+    closingValue: z.ZodOptional<z.ZodNumber>;
+    hsnCode: z.ZodOptional<z.ZodString>;
+    gstRate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type StockItem = z.infer<typeof StockItemSchema>;
+declare const StockItemInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    group: z.ZodDefault<z.ZodString>;
+    unit: z.ZodString;
+    hsnCode: z.ZodOptional<z.ZodString>;
+    gstRate: z.ZodOptional<z.ZodNumber>;
+    openingQty: z.ZodOptional<z.ZodNumber>;
+    openingRate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type StockItemInput = z.infer<typeof StockItemInputSchema>;
+declare const CompanySchema: z.ZodObject<{
+    name: z.ZodString;
+    guid: z.ZodString;
+    startingFrom: z.ZodOptional<z.ZodString>;
+    endingAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Company = z.infer<typeof CompanySchema>;
+declare const OutstandingEntrySchema: z.ZodObject<{
+    ledgerName: z.ZodString;
+    voucherNumber: z.ZodString;
+    voucherDate: z.ZodCoercedDate<unknown>;
+    dueDate: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+    pendingAmount: z.ZodNumber;
+    overdueDays: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type OutstandingEntry = z.infer<typeof OutstandingEntrySchema>;
+
+declare const lineItemSchema: z.ZodObject<{
+    stockItem: z.ZodString;
+    quantity: z.ZodNumber;
+    rate: z.ZodNumber;
+    amount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type LineItem = z.infer<typeof lineItemSchema>;
+declare const SalesVoucherInputSchema: z.ZodObject<{
+    party: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        stockItem: z.ZodString;
+        quantity: z.ZodNumber;
+        rate: z.ZodNumber;
+        amount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    salesLedger: z.ZodDefault<z.ZodString>;
+    taxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ledger: z.ZodString;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>>;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Sales">;
+}, z.core.$strip>;
+type SalesVoucherInput = z.infer<typeof SalesVoucherInputSchema>;
+declare const PurchaseVoucherInputSchema: z.ZodObject<{
+    party: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        stockItem: z.ZodString;
+        quantity: z.ZodNumber;
+        rate: z.ZodNumber;
+        amount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    purchaseLedger: z.ZodDefault<z.ZodString>;
+    taxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ledger: z.ZodString;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>>;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Purchase">;
+}, z.core.$strip>;
+type PurchaseVoucherInput = z.infer<typeof PurchaseVoucherInputSchema>;
+declare const PaymentVoucherInputSchema: z.ZodObject<{
+    debitLedger: z.ZodString;
+    creditLedger: z.ZodString;
+    amount: z.ZodNumber;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Payment">;
+}, z.core.$strip>;
+type PaymentVoucherInput = z.infer<typeof PaymentVoucherInputSchema>;
+declare const ReceiptVoucherInputSchema: z.ZodObject<{
+    debitLedger: z.ZodString;
+    creditLedger: z.ZodString;
+    amount: z.ZodNumber;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Receipt">;
+}, z.core.$strip>;
+type ReceiptVoucherInput = z.infer<typeof ReceiptVoucherInputSchema>;
+declare const JournalVoucherInputSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        ledger: z.ZodString;
+        type: z.ZodEnum<{
+            Debit: "Debit";
+            Credit: "Credit";
+        }>;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Journal">;
+}, z.core.$strip>;
+type JournalVoucherInput = z.infer<typeof JournalVoucherInputSchema>;
+declare const VoucherInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    party: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        stockItem: z.ZodString;
+        quantity: z.ZodNumber;
+        rate: z.ZodNumber;
+        amount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    salesLedger: z.ZodDefault<z.ZodString>;
+    taxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ledger: z.ZodString;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>>;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Sales">;
+}, z.core.$strip>, z.ZodObject<{
+    party: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        stockItem: z.ZodString;
+        quantity: z.ZodNumber;
+        rate: z.ZodNumber;
+        amount: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    purchaseLedger: z.ZodDefault<z.ZodString>;
+    taxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ledger: z.ZodString;
+        amount: z.ZodNumber;
+    }, z.core.$strip>>>;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Purchase">;
+}, z.core.$strip>, z.ZodObject<{
+    debitLedger: z.ZodString;
+    creditLedger: z.ZodString;
+    amount: z.ZodNumber;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Payment">;
+}, z.core.$strip>, z.ZodObject<{
+    debitLedger: z.ZodString;
+    creditLedger: z.ZodString;
+    amount: z.ZodNumber;
+    date: z.ZodCoercedDate<unknown>;
+    narration: z.ZodOptional<z.ZodString>;
+    voucherNumber: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    voucherType: z.ZodLiteral<"Receipt">;
+}, z.core.$strip>], "voucherType">;
+type VoucherInput = SalesVoucherInput | PurchaseVoucherInput | PaymentVoucherInput | ReceiptVoucherInput | JournalVoucherInput;
+/** Exhaustiveness helper: pass an unreachable VoucherInput here in a
+ * `default` switch branch — if a new voucher type is added to the union
+ * without updating the builder, this fails to compile instead of failing at
+ * runtime in front of a customer. */
+declare function assertNever(x: never): never;
+interface VoucherCreateResult {
+    voucherNumber: string;
+    guid: string;
+    alteredOn: Date;
+}
+
+/**
+ * Tally's XML is XML-shaped but not XML-clean. Two encoding quirks matter
+ * enough to centralize here rather than handle ad hoc in every builder:
+ *
+ * 1. Standard XML entities (&, <, >, ", ') still need escaping — Tally's
+ *    parser is otherwise normal on that front.
+ * 2. Tally has its own non-standard "empty but present" marker, &#4;, used
+ *    in some master-import contexts to distinguish "field omitted" from
+ *    "field explicitly cleared". We expose escapeXml() for normal text and
+ *    leave &#4; as an explicit opt-in (EMPTY_MARKER) so builders don't emit
+ *    it by accident.
+ */
+declare const EMPTY_MARKER = "&#4;";
+declare function escapeXml(value: string): string;
+/** Tally dates are YYYYMMDD with no separators, always. */
+declare function formatTallyDate(date: Date): string;
+/**
+ * Tally renders negative ledger amounts as a sign on the number, but which
+ * sign means debit vs credit flips depending on whether you're looking at a
+ * Sales-side or Purchase-side ledger entry. Rather than push that
+ * ambiguity onto every builder, callers pass an explicit `isDebit` flag and
+ * this function produces the signed string Tally expects: debit entries are
+ * positive, credit entries are negative, full stop, at the wire level.
+ */
+declare function formatSignedAmount(amount: number, isDebit: boolean): string;
+type EnvelopeRequestType = "Import Data" | "Export Data";
+interface EnvelopeOptions {
+    requestType: EnvelopeRequestType;
+    /** "Vouchers" | "Masters" | "Collection" | "Company" — Tally's REPORTNAME/ID context */
+    id: string;
+    company?: string;
+    staticVariables?: Record<string, string>;
+}
+/**
+ * Wraps an inner payload in Tally's outer envelope. This is the one place
+ * both sublanguages meet — everything sublanguage-specific lives in the
+ * builders that call this, not in here.
+ *
+ * Import (write) requests use <IMPORTDATA> and carry the actual master/
+ * voucher XML inside <REQUESTDATA>. Export (read/collection) requests use
+ * <EXPORTDATA> and have no REQUESTDATA section at all — the field list comes
+ * from the report/collection definition Tally already knows about via
+ * REPORTNAME, not from anything we send. Passing bodyXml on an export
+ * request is a no-op by design, not an oversight.
+ */
+declare function buildEnvelope(options: EnvelopeOptions, bodyXml?: string): string;
+
+/**
+ * Tally master imports are wrapped in a TALLYMESSAGE envelope, with the
+ * object's NAME duplicated as both an XML attribute on the tag (how Tally
+ * identifies *which* object this is, for upsert-by-name semantics) and as a
+ * <NAME> child element (how Tally reads the field value). Forgetting either
+ * one is a common hand-rolled-XML bug this builder exists to make
+ * impossible.
+ */
+declare function buildCreateLedgerXml(input: LedgerInput): string;
+declare function buildCreateStockItemXml(input: StockItemInput): string;
+
+/**
+ * The exhaustive switch: TypeScript will refuse to compile this file if a
+ * sixth voucher type is added to VoucherInput without a matching case here —
+ * that's the whole point of routing every variant through assertNever in
+ * the default branch instead of leaving it untyped.
+ */
+declare function buildVoucherXml(input: VoucherInput): string;
+
+/**
+ * Export requests don't carry a request body the way imports do — the field
+ * list comes from Tally's built-in report/collection names. We pin to
+ * Tally's native report names rather than hand-rolling TDL collection
+ * definitions, which keeps this builder simple at the cost of being unable
+ * to add custom fields. (A custom-TDL collection layer is a reasonable
+ * Phase 2 addition once the basic reads are solid.)
+ */
+declare function buildGetCompaniesXml(): string;
+declare function buildGetLedgersXml(company?: string): string;
+declare function buildGetStockItemsXml(company?: string): string;
+declare function buildGetOutstandingXml(company?: string): string;
+declare function buildPingXml(): string;
+
+/**
+ * Parses a response to an Import Data request (createLedger, createVoucher,
+ * etc). Two-pass by design: first parse the XML unconditionally, then
+ * inspect the parsed tree for error markers. We never string-match on raw
+ * XML for "LINEERROR" — that breaks the moment Tally changes whitespace or
+ * attribute order, which it does between versions.
+ */
+declare function parseImportResponse(rawXml: string): Result<VoucherCreateResult, TallyError>;
+
+declare function parseLedgerCollection(rawXml: string): Result<Ledger[], TallyError>;
+declare function parseStockItemCollection(rawXml: string): Result<StockItem[], TallyError>;
+declare function parseCompanyCollection(rawXml: string): Result<Company[], TallyError>;
+declare function parseOutstandingCollection(rawXml: string): Result<OutstandingEntry[], TallyError>;
+
+declare class Tally {
+    private readonly transport;
+    private readonly company?;
+    constructor(config: TallyConfig);
+    ping(): Promise<Result<true, TallyError>>;
+    getCompanies(): Promise<Result<Company[], TallyError>>;
+    getLedgers(): Promise<Result<Ledger[], TallyError>>;
+    /** Alias matching the original product sketch's naming. */
+    getCustomers(): Promise<Result<Ledger[], TallyError>>;
+    getStockItems(): Promise<Result<StockItem[], TallyError>>;
+    getOutstanding(): Promise<Result<OutstandingEntry[], TallyError>>;
+    createLedger(input: LedgerInput): Promise<Result<VoucherCreateResult, TallyError>>;
+    createStockItem(input: StockItemInput): Promise<Result<VoucherCreateResult, TallyError>>;
+    createVoucher(input: VoucherInput): Promise<Result<VoucherCreateResult, TallyError>>;
+    /**
+     * Convenience wrapper matching the original sketch's `createInvoice()`
+     * signature — expands into a full SalesVoucherInput (voucherType: "Sales")
+     * before going through the same validated path as createVoucher(). Kept
+     * separate from createVoucher() because "invoice" maps to a Sales voucher
+     * specifically, and spelling that out here means callers coming from
+     * other invoicing tools (Stripe, Zoho) don't need to know Tally's
+     * voucherType vocabulary at all.
+     */
+    createInvoice(input: {
+        customer: string;
+        date: Date;
+        items: SalesVoucherInput["items"];
+        salesLedger?: string;
+        taxes?: SalesVoucherInput["taxes"];
+        reference?: string;
+        narration?: string;
+    }): Promise<Result<VoucherCreateResult, TallyError>>;
+    /**
+     * Returns JSON-Schema-shaped tool definitions (derived from the same Zod
+     * schemas used for validation, so the agent-facing contract can never
+     * drift from what the SDK actually accepts) for OpenAI-style function
+     * calling, LangGraph, Mastra, or a hand-rolled MCP server. Each `handler`
+     * closes over `this`, so a caller can wire these straight into an agent
+     * framework's tool registry without writing adapter glue.
+     */
+    tools(): readonly [{
+        readonly name: "getCustomers";
+        readonly description: "List all Sundry Debtor ledgers (customers) in the active Tally company.";
+        readonly parameters: z.ZodObject<{}, z.core.$strip>;
+        readonly handler: () => Promise<Result<{
+            name: string;
+            guid: string;
+            group: string;
+            gstin?: string | undefined;
+            closingBalance?: number | undefined;
+            state?: string | undefined;
+        }[], TallyError>>;
+    }, {
+        readonly name: "getOutstanding";
+        readonly description: "Get outstanding (unpaid) receivable bills across all customers.";
+        readonly parameters: z.ZodObject<{}, z.core.$strip>;
+        readonly handler: () => Promise<Result<{
+            ledgerName: string;
+            voucherNumber: string;
+            voucherDate: Date;
+            pendingAmount: number;
+            dueDate?: Date | undefined;
+            overdueDays?: number | undefined;
+        }[], TallyError>>;
+    }, {
+        readonly name: "createInvoice";
+        readonly description: "Create a sales invoice for a customer with one or more line items.";
+        readonly parameters: z.ZodObject<{
+            customer: z.ZodString;
+            date: z.ZodCoercedDate<unknown>;
+            items: z.ZodArray<z.ZodObject<{
+                stockItem: z.ZodString;
+                quantity: z.ZodNumber;
+                rate: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        readonly handler: (args: {
+            customer: string;
+            date: Date;
+            items: SalesVoucherInput["items"];
+        }) => Promise<Result<VoucherCreateResult, TallyError>>;
+    }, {
+        readonly name: "createLedger";
+        readonly description: "Create a new ledger account (e.g. a new customer or supplier) in Tally.";
+        readonly parameters: z.ZodObject<{
+            name: z.ZodString;
+            group: z.ZodString;
+            gstin: z.ZodOptional<z.ZodString>;
+            openingBalance: z.ZodOptional<z.ZodNumber>;
+            openingBalanceType: z.ZodOptional<z.ZodEnum<{
+                Debit: "Debit";
+                Credit: "Credit";
+            }>>;
+            address: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            state: z.ZodOptional<z.ZodString>;
+            pincode: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        readonly handler: (args: LedgerInput) => Promise<Result<VoucherCreateResult, TallyError>>;
+    }];
+}
+
+/**
+ * Tally's HTTP-XML server takes every request as a raw XML POST body to the
+ * root path — there's no REST routing, no headers carrying semantics, just
+ * "post some XML, get some XML back". That makes this transport layer
+ * unusually thin: its only real job is turning network-level failures
+ * (DNS, connection refused, timeout) into typed errors and retrying *only*
+ * those — never retrying a request that reached Tally and got a real
+ * response, because Tally-side rejections aren't transient.
+ */
+declare class TallyTransport {
+    private readonly config;
+    private readonly retries;
+    constructor(config: TallyConfig);
+    send(requestXml: string): Promise<Result<string, TallyError>>;
+}
+
+export { type Company, CompanySchema, EMPTY_MARKER, type EnvelopeOptions, type EnvelopeRequestType, type JournalVoucherInput, JournalVoucherInputSchema, type Ledger, type LedgerInput, LedgerInputSchema, LedgerSchema, type LineItem, type OutstandingEntry, OutstandingEntrySchema, type PaymentVoucherInput, PaymentVoucherInputSchema, type PurchaseVoucherInput, PurchaseVoucherInputSchema, type ReceiptVoucherInput, ReceiptVoucherInputSchema, type Result, type SalesVoucherInput, SalesVoucherInputSchema, type StockItem, type StockItemInput, StockItemInputSchema, StockItemSchema, Tally, type TallyConfig, type TallyError, type TallyErrorCode, TallyTransport, type VoucherCreateResult, type VoucherInput, VoucherInputSchema, assertNever, buildCreateLedgerXml, buildCreateStockItemXml, buildEnvelope, buildGetCompaniesXml, buildGetLedgersXml, buildGetOutstandingXml, buildGetStockItemsXml, buildPingXml, buildVoucherXml, err, escapeXml, formatSignedAmount, formatTallyDate, ok, parseCompanyCollection, parseImportResponse, parseLedgerCollection, parseOutstandingCollection, parseStockItemCollection, tallyError, unwrap };