@sixtyninecommerce/admin 0.6.0 → 0.8.0

package/dist/documents/index.d.ts

@@ -0,0 +1,432 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { Call } from '../types.js';
+/**
+ * Which document a call is about. The platform issues three, and every method
+ * here that takes a type takes one of these.
+ */
+export type DocumentType = 'invoice' | 'credit-note' | 'packing-slip';
+/** An issued invoice. Money is in MINOR UNITS, as everywhere in this SDK. */
+export interface Invoice {
+    id: string;
+    invoiceNumber: string;
+    /** Issue date, `YYYY-MM-DD`. */
+    invoicedOn: string;
+    orderId: string;
+    languageCode: string;
+    storageKey: string;
+    totalWithTax: number;
+    currencyCode: string;
+    note: string | null;
+    /** Set once a void & reissue reversed it; null while the invoice is live. */
+    voidedOn: string | null;
+    /** `standard` for the order's invoice, `supplementary` for an under-charge billed on top. */
+    kind: string;
+    createdAt: string;
+}
+/** An issued credit note. `totalWithTax` is the POSITIVE value of the credit. */
+export interface CreditNote {
+    id: string;
+    creditNoteNumber: string;
+    issuedOn: string;
+    totalWithTax: number;
+    currencyCode: string;
+    reason: string;
+    invoiceId: string;
+    /** `correction` | `cancellation` | `return` | `adjustment`. */
+    kind: string;
+    /** Null until the PDF has been rendered and stored. */
+    storageKey: string | null;
+    createdAt: string;
+}
+export interface PackingSlip {
+    id: string;
+    packingSlipNumber: string;
+    fulfillmentId: string;
+    languageCode: string;
+    storageKey: string;
+    createdAt: string;
+}
+/**
+ * One block as supplied at generation time.
+ *
+ * Validated against the registered schema AT THAT VERSION. An unknown key, a
+ * stale `schemaVersion` or data the schema refuses rejects the WHOLE document:
+ * the platform never issues a numbered document that silently lacks a block
+ * the caller asked for.
+ */
+export interface DocumentExtensionInput {
+    key: string;
+    /** The version the data was written against. A stale one is refused, never coerced. */
+    schemaVersion: number;
+    data: unknown;
+}
+/**
+ * Most blocks one document may carry. A longer list refuses the whole document
+ * (`DOCUMENT_EXTENSION_INVALID`) rather than issuing a numbered one that
+ * dropped the overflow — a document is a page, not a feed.
+ */
+export declare const MAX_DOCUMENT_EXTENSIONS = 10;
+/**
+ * A registered extension block.
+ *
+ * ## The schema grammar is BOUNDED, on purpose
+ *
+ * This platform accepts exactly fifteen JSON Schema keywords and refuses any
+ * other one BY NAME at registration — `DOCUMENT_EXTENSION_SCHEMA_KEYWORD_UNSUPPORTED`,
+ * with the keyword and the JSON Pointer in `details[]`. Thirteen of them
+ * constrain the data; `title` and `description` are annotations with nothing to
+ * check. The fifteen:
+ *
+ * **And a keyword must sit on a type it can constrain**, or it is refused the
+ * same way, naming the keyword AND the type: `minLength` on an `integer`
+ * constrains nothing, and an `enum` on an `object` matches nothing so it
+ * refuses every value. `minLength`/`maxLength`/`pattern` belong to a `string`,
+ * `minimum`/`maximum` to a `number` or `integer`, `minItems`/`maxItems`/`items`
+ * to an `array`, `properties`/`required`/`additionalProperties` to an `object`,
+ * `enum` to the four scalar types; `type`, `title` and `description` go
+ * anywhere. A PIN is a `string` with `minLength`, not an `integer` with one.
+ *
+ * `type`, `title`, `description`, `properties`, `required`,
+ * `additionalProperties`, `items`, `enum`, `minLength`, `maxLength`,
+ * `minimum`, `maximum`, `minItems`, `maxItems`, `pattern`.
+ *
+ * Six types are accepted: `object`, `array`, `string`, `number`, `integer`,
+ * `boolean`. One deliberate difference from JSON Schema: `additionalProperties`
+ * defaults to **false**, so a block cannot carry unvalidated fields onto a
+ * document.
+ *
+ * A keyword this list does not name is refused rather than ignored — a schema
+ * that appears to constrain something it does not is worse than one that is
+ * rejected while the merchant is still editing it.
+ *
+ * ## The template fragment is allow-listed
+ *
+ * Each node names its kind in `node` — `{ node: 'text', text: 'HS {{ /hsCode }}' }`
+ * — and the five kinds are `text`, `stack`, `columns`, `table` and `repeat`.
+ * `{{ /json/pointer }}` placeholders are filled from the block's data, and text
+ * is never interpreted as document markup. Margins are bounded and cannot be
+ * negative (a negative one would draw the block over the document's own
+ * totals), a `table`'s rows must all be the same width, and a `repeat` belongs
+ * inside a `stack` rather than being a table cell — each would otherwise throw
+ * inside the PDF engine after the document had been numbered.
+ *
+ * A placeholder that resolves to nothing,
+ * or to an object or array, is refused AT GENERATION
+ * (`DOCUMENT_EXTENSION_PLACEHOLDER_UNRESOLVED`) rather than printed as an empty
+ * string or `[object Object]`.
+ */
+export interface DocumentExtensionSchema {
+    key: string;
+    /**
+     * `string[]`, not `DocumentType[]`, on purpose: the platform may additively
+     * grow a fourth kind, and an SDK a version behind would then be handing back
+     * a value typed as one of the three it knows. Compare against
+     * {@link DocumentType} members rather than assuming exhaustiveness.
+     */
+    documentTypes: string[];
+    /** Bumped by every re-registration. A generation must name the version it wrote against. */
+    schemaVersion: number;
+    jsonSchema: unknown;
+    templateFragment: unknown;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface RegisterDocumentExtensionInput {
+    /** Lower-case kebab handle, at most 64 characters. */
+    key: string;
+    documentTypes: DocumentType[];
+    /** See {@link DocumentExtensionSchema} for the fifteen keywords this platform accepts. */
+    jsonSchema: unknown;
+    /** See {@link DocumentExtensionSchema} for the allow-listed fragment nodes. */
+    templateFragment: unknown;
+}
+/** One line of a document, in minor units. Every money field is null on a packing slip. */
+export interface DocumentDataLine {
+    description: string;
+    sku: string;
+    quantity: number;
+    unitPriceNet: number | null;
+    unitPriceWithTax: number | null;
+    taxRate: number | null;
+    lineTotalNet: number | null;
+    lineTotalWithTax: number | null;
+}
+export interface DocumentDataTaxRow {
+    taxRate: number;
+    taxBase: number;
+    taxTotal: number;
+}
+export interface DocumentDataTotals {
+    /** Net subtotal (lines and surcharges, excluding shipping). */
+    subTotal: number;
+    shippingTotal: number;
+    taxTotal: number;
+    totalWithTax: number;
+}
+/**
+ * Where a document's number came from.
+ *
+ * `scope` is modelled rather than assumed. Today every series is per channel;
+ * multi-region will issue per legal entity (spec §12.2), and a consumer that
+ * reads `scope`/`scopeId` keeps working when that lands — which is why the
+ * field exists before there is a second value for it. Numbering itself stays
+ * platform-owned: there is no SDK method that allocates or reserves a number.
+ */
+export interface DocumentDataNumbering {
+    scope: 'channel';
+    scopeId: string;
+    /** The configured prefix of the series, when the store set one. */
+    series: string | null;
+    number: string;
+}
+export interface DocumentDataParty {
+    companyName?: string;
+    fullName: string;
+    addressLine1: string;
+    addressLine2?: string;
+    postalCode: string;
+    city: string;
+    province?: string;
+    country?: string;
+}
+/** WHO issued the document — the legal entity whose identity is printed on it. */
+export interface DocumentDataIssuer {
+    name: string;
+    address: {
+        line1: string;
+        line2?: string;
+        postalCode: string;
+        city: string;
+        province?: string;
+        country?: string;
+    };
+    vatNumber?: string;
+    registrationNumber?: string;
+}
+/**
+ * The numbered facts a document was built from — enough to render your own
+ * document from the same figures the platform printed.
+ */
+export interface DocumentData {
+    type: DocumentType;
+    id: string;
+    numbering: DocumentDataNumbering;
+    /** `YYYY-MM-DD`, as the document stored it. */
+    issuedOn: string;
+    languageCode: string;
+    /** Null on a packing slip, which carries no money. */
+    currencyCode: string | null;
+    issuer: DocumentDataIssuer;
+    recipient: DocumentDataParty | null;
+    order: {
+        id: string;
+        code: string;
+    } | null;
+    lines: DocumentDataLine[];
+    /**
+     * Null — never an empty array — when the document never stated a per-rate
+     * split. A lump-sum credit note on a mixed-rate order is the case: "it never
+     * said" must not read as "it said nothing is taxed".
+     */
+    taxSummary: DocumentDataTaxRow[] | null;
+    totals: DocumentDataTotals | null;
+    /**
+     * The gross the document was NUMBERED with, straight off its own row — the
+     * figure every downstream operation (credit ceiling, reversal, refund) acts
+     * on. Null on a packing slip.
+     */
+    issuedTotalWithTax: number | null;
+    /**
+     * Whether {@link totals} still reconciles with {@link issuedTotalWithTax}.
+     *
+     * The question only really arises on a STANDARD invoice: it is the one
+     * document that derives its lines from the ORDER, and an order can be
+     * modified after the invoice was numbered. The document is immutable, the
+     * order is not — so the two CAN disagree, and you are told rather than handed
+     * a silently re-derived total under the issued number. A credit note states
+     * its own lines and always reports `true`; a packing slip carries no money
+     * and reports null.
+     */
+    reconciled: boolean | null;
+    /** Exactly what the document froze — never the store's current registration. */
+    extensions: Array<{
+        key: string;
+        schemaVersion: number;
+        data: unknown;
+        templateFragment: unknown;
+    }>;
+    invoice?: {
+        kind: string;
+        dueOn: string | null;
+        voidedOn: string | null;
+        note: string | null;
+    };
+    creditNote?: {
+        kind: string;
+        reason: string;
+        invoiceId: string;
+    };
+    packingSlip?: {
+        fulfillmentId: string;
+        orderCodes: string[];
+    };
+}
+/** What `generate` needs, per document type. */
+export interface GenerateDocumentOptions extends Call {
+    /**
+     * Invoice date, `YYYY-MM-DD`. REQUIRED for an invoice and rejected for a
+     * packing slip. Deliberately not defaulted: a document date decides which
+     * period the money books into, and the caller's clock is not the store's.
+     */
+    invoicedOn?: string;
+    languageCode?: string;
+    /** Rendered on the invoice and in the invoice email. Invoices only. */
+    note?: string;
+    /**
+     * Tenant-registered blocks, at most {@link MAX_DOCUMENT_EXTENSIONS}. An
+     * invalid, duplicate or over-long list refuses the whole generation; nothing
+     * is dropped.
+     */
+    extensions?: DocumentExtensionInput[];
+}
+export interface IssuePartialCreditNoteInput {
+    orderId: string;
+    /** Why the credit was issued — required, printed on the note. */
+    reason: string;
+    /** What is being credited. The credited total is their sum; it is never stated separately. */
+    lines: DocumentLineInput[];
+    /** The invoice to credit; defaults to the order's newest live one. */
+    invoiceId?: string;
+    /** Also refund the credited amount against this payment. Omit for a document-only credit. */
+    refundPaymentId?: string;
+    /** Blocks for the credit note. An invalid one refuses the issue BEFORE the refund moves. */
+    extensions?: DocumentExtensionInput[];
+}
+export interface IssueSupplementaryInvoiceInput {
+    orderId: string;
+    /** The live invoice this one adds to; both stay owed. */
+    supplementsInvoiceId: string;
+    lines: DocumentLineInput[];
+    invoicedOn?: string;
+    languageCode?: string;
+    note?: string;
+    extensions?: DocumentExtensionInput[];
+}
+/** One line a document states itself, rather than deriving from the order. */
+export interface DocumentLineInput {
+    description: string;
+    sku?: string;
+    /** The order line this row was prefilled from; omit for a free-form row. */
+    orderLineId?: string;
+    quantity: number;
+    /** Minor units, in the basis named by `unitPriceBasis`. May be negative for a discount row. */
+    unitPrice: number;
+    unitPriceBasis: 'net' | 'gross';
+    /** Percentage; may be fractional. 0 means an untaxed line. */
+    taxRate: number;
+}
+export interface SendInvoiceEmailInput {
+    orderId: string;
+    recipientsTo: string[];
+    recipientsCc?: string[];
+}
+/** The store's extension-block registry. Reading needs `ReadSettings`, writing `UpdateSettings`. */
+export interface DocumentExtensionsModule {
+    /**
+     * The USABLE set: the newest version of each key.
+     *
+     * A superseded version is deliberately absent. It still exists — every
+     * document issued against it froze its own copy and still redraws — but
+     * nothing new can be written against it, so offering it as a choice would
+     * only invite a `DOCUMENT_EXTENSION_VERSION_MISMATCH`.
+     */
+    list(options?: Call): Promise<Page<DocumentExtensionSchema>>;
+    /**
+     * Register a block, or a NEW VERSION of one. A key is never edited in place,
+     * so documents already issued keep the schema and fragment they carry.
+     */
+    register(input: RegisterDocumentExtensionInput, options?: Call): Promise<DocumentExtensionSchema>;
+    /**
+     * Stop a key being usable on new documents. True when something was removed,
+     * false when there was nothing — so a repeated delete is not an error.
+     * Documents already issued with it are untouched.
+     */
+    delete(key: string, options?: Call): Promise<boolean>;
+}
+/**
+ * The store's documents: issuing them, reading the facts they were built from,
+ * and the tenant-registered blocks that extend them (headless spec §8.5).
+ *
+ * **Coded refusals**, delivered as GraphQL errors with `extensions.code`:
+ * `DOCUMENT_EXTENSION_NOT_FOUND` (→ `NotFoundError`) for a key this store has
+ * not registered; `DOCUMENT_EXTENSION_VERSION_MISMATCH` (→ `ConflictError`)
+ * when the key exists but not at the version you wrote against;
+ * `DOCUMENT_EXTENSION_WRONG_DOCUMENT_TYPE`, `DOCUMENT_EXTENSION_INVALID`,
+ * `DOCUMENT_EXTENSION_PLACEHOLDER_UNRESOLVED`,
+ * `DOCUMENT_EXTENSION_SCHEMA_INVALID`,
+ * `DOCUMENT_EXTENSION_SCHEMA_KEYWORD_UNSUPPORTED`,
+ * `DOCUMENT_EXTENSION_TEMPLATE_INVALID` and `INVALID_DOCUMENT_EXTENSION_KEY`
+ * (→ `ValidationError`). A refusal about several fields at once carries
+ * `error.details`: one entry per JSON Pointer, its `field` the pointer and its
+ * `code` the schema keyword that refused — so a form marks each offending field
+ * rather than showing one joined sentence.
+ *
+ * `idempotencyKey` on these calls is recorded on the wire and acts on nothing:
+ * the Admin API is GraphQL and has no header for it (see {@link Call}). A
+ * repeated `generate` is a second attempt, which for an invoice the platform
+ * refuses on its own — an order carries at most one live standard invoice.
+ */
+export interface DocumentsModule {
+    /**
+     * Issue a document.
+     *
+     * `subjectId` is what the document is FOR, which differs by type: an order id
+     * for an invoice, a FULFILLMENT id for a packing slip. A credit note is not
+     * issued here — it credits an invoice and needs a reason and lines, so it has
+     * its own method ({@link issuePartialCreditNote}).
+     *
+     * An invoice REQUIRES `invoicedOn`: the document date decides which period
+     * the money books into, and the caller's clock is not the store's. The
+     * overloads put that in the type system, and refuse an invoice-only option on
+     * a packing slip the same way.
+     */
+    generate(subjectId: string, type: 'invoice', options: GenerateDocumentOptions & {
+        invoicedOn: string;
+    }): Promise<Invoice>;
+    generate(subjectId: string, type: 'packing-slip', options?: Omit<GenerateDocumentOptions, 'invoicedOn' | 'note'>): Promise<PackingSlip>;
+    /** The numbered facts a document was built from. Needs `ReadOrder`. */
+    data(documentId: string, type: DocumentType, options?: Call): Promise<DocumentData>;
+    /** Every invoice of an order, including voided ones. */
+    invoices(orderId: string, options?: Call): Promise<Page<Invoice>>;
+    /** Every credit note of an order. */
+    creditNotes(orderId: string, options?: Call): Promise<Page<CreditNote>>;
+    /**
+     * Render what an invoice WOULD look like, without numbering or storing one.
+     * Returns the PDF bytes (the wire carries base64; this decodes it).
+     */
+    previewInvoice(orderId: string, options: {
+        invoicedOn: string;
+        languageCode?: string;
+        note?: string;
+    } & Call): Promise<Uint8Array>;
+    /** Email an order's invoice. True when the dispatch was accepted. */
+    sendInvoiceEmail(input: SendInvoiceEmailInput, options?: Call): Promise<boolean>;
+    /** Credit PART of a still-valid invoice; the invoice keeps standing. */
+    issuePartialCreditNote(input: IssuePartialCreditNoteInput, options?: Call): Promise<CreditNote>;
+    /** Bill an under-charge as a supplementary invoice; both invoices stay owed. */
+    issueSupplementaryInvoice(input: IssueSupplementaryInvoiceInput, options?: Call): Promise<Invoice>;
+    extensions: DocumentExtensionsModule;
+}
+export declare const GENERATE_INVOICE_MUTATION = "\n  mutation GenerateInvoice(\n    $orderId: ID!\n    $invoicedOn: String!\n    $languageCode: String\n    $note: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generateInvoice(\n      orderId: $orderId\n      invoicedOn: $invoicedOn\n      languageCode: $languageCode\n      note: $note\n      extensions: $extensions\n    ) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  kind\n  createdAt\n }\n  }\n";
+export declare const GENERATE_PACKING_SLIP_MUTATION = "\n  mutation GeneratePackingSlip(\n    $fulfillmentId: ID!\n    $languageCode: String\n    $extensions: [DocumentExtensionInput!]\n  ) {\n    generatePackingSlip(\n      fulfillmentId: $fulfillmentId\n      languageCode: $languageCode\n      extensions: $extensions\n    ) { \n  id\n  packingSlipNumber\n  fulfillmentId\n  languageCode\n  storageKey\n  createdAt\n }\n  }\n";
+export declare const DOCUMENT_DATA_QUERY = "\n  query DocumentData($documentId: ID!, $type: DocumentType!) {\n    documentData(documentId: $documentId, type: $type)\n  }\n";
+export declare const ORDER_INVOICES_QUERY = "\n  query OrderInvoices($orderId: ID!) {\n    orderInvoices(orderId: $orderId) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  kind\n  createdAt\n }\n  }\n";
+export declare const ORDER_CREDIT_NOTES_QUERY = "\n  query OrderCreditNotes($orderId: ID!) {\n    orderCreditNotes(orderId: $orderId) { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  storageKey\n  createdAt\n }\n  }\n";
+export declare const PREVIEW_INVOICE_MUTATION = "\n  mutation PreviewInvoice($orderId: ID!, $invoicedOn: String!, $languageCode: String, $note: String) {\n    previewInvoice(orderId: $orderId, invoicedOn: $invoicedOn, languageCode: $languageCode, note: $note)\n  }\n";
+export declare const SEND_INVOICE_EMAIL_MUTATION = "\n  mutation SendInvoiceEmail($input: SendInvoiceEmailInput!) {\n    sendInvoiceEmail(input: $input)\n  }\n";
+export declare const ISSUE_PARTIAL_CREDIT_NOTE_MUTATION = "\n  mutation IssuePartialCreditNote($input: IssuePartialCreditNoteInput!) {\n    issuePartialCreditNote(input: $input) { \n  id\n  creditNoteNumber\n  issuedOn\n  totalWithTax\n  currencyCode\n  reason\n  invoiceId\n  kind\n  storageKey\n  createdAt\n }\n  }\n";
+export declare const ISSUE_SUPPLEMENTARY_INVOICE_MUTATION = "\n  mutation IssueSupplementaryInvoice($input: IssueSupplementaryInvoiceInput!) {\n    issueSupplementaryInvoice(input: $input) { \n  id\n  invoiceNumber\n  invoicedOn\n  orderId\n  languageCode\n  storageKey\n  totalWithTax\n  currencyCode\n  note\n  voidedOn\n  kind\n  createdAt\n }\n  }\n";
+export declare const DOCUMENT_EXTENSIONS_QUERY = "\n  query DocumentExtensions {\n    documentExtensions { \n  key\n  documentTypes\n  schemaVersion\n  jsonSchema\n  templateFragment\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const REGISTER_DOCUMENT_EXTENSION_MUTATION = "\n  mutation RegisterDocumentExtension($input: RegisterDocumentExtensionInput!) {\n    registerDocumentExtension(input: $input) { \n  key\n  documentTypes\n  schemaVersion\n  jsonSchema\n  templateFragment\n  createdAt\n  updatedAt\n }\n  }\n";
+export declare const DELETE_DOCUMENT_EXTENSION_MUTATION = "\n  mutation DeleteDocumentExtension($key: String!) {\n    deleteDocumentExtension(key: $key)\n  }\n";
+export declare function createDocumentsModule(transport: Transport): DocumentsModule;