@timbro/invoices 0.8.2 → 0.9.0-next.0

package/README.md

@@ -1,308 +1,145 @@
 # @timbro/invoices
 
-Issue Dominican electronic invoices (e-CF) from your application, ERP, or POS with one configured client. Invoice issuance and payment collection have separate lifecycles. Use `@timbro/payments` when you also need Timbro to collect money through Checkout.
+Create, retrieve, and download Dominican electronic invoices from your application, ERP, or POS. Invoice issuance and payment collection have separate lifecycles. Use `@timbro/payments` when you also need to collect money through Checkout.
 
-Rust owns the fiscal wire contract. This SDK uses generated operation bindings and validators at every HTTP boundary.
+Use a server-side key with the Invoices capability. The client defaults to `https://api.timbro.do`; a dedicated Invoice installation uses the same document calls with its own `baseUrl` and Source key. The credential selects the business and environment.
 
 ```ts
-import { createTimbroClient } from "@timbro/invoices";
-import type { FiscalDocument } from "@timbro/invoices";
+import { createTimbroInvoices, type InvoiceRequest } from "@timbro/invoices";
 
-const credential = process.env.TIMBRO_CREDENTIAL;
-if (credential === undefined || credential.trim() === "") {
-  throw new Error("TIMBRO_CREDENTIAL is required");
+const apiKey = process.env.TIMBRO_API_KEY;
+if (apiKey === undefined || apiKey.trim() === "") {
+  throw new Error("TIMBRO_API_KEY is required");
 }
-
-const document: FiscalDocument = {
-  kind: "type31",
-  snapshot: {
-    currency: "DOP",
-    incomeType: "01",
-    paymentType: "1",
-    buyer: { taxId: "101234567", legalName: "Example Buyer" },
-    lines: [{
-      sourceLineId: "line-1",
-      name: "Example product",
-      quantity: "1.00",
-      measurementUnit: "31",
-      unitPrice: "118.00",
-      billingIndicator: "1",
-      goodsOrServiceIndicator: "1",
-    }],
-    paymentAllocations: [{ method: "1", amount: "118.00" }],
-  },
-};
-
-const timbro = createTimbroClient({
-  baseUrl: "https://stamp.example.test",
-  authentication: { mode: "source_connection", credential },
-});
-
-const operation = await timbro.fiscalDocuments.issue({
-  source: {
-    id: "checkout-order-1001",
-    version: "v1",
-  },
-  document,
-  numberingInstruction: { kind: "centralAssignment" },
-  printedRepresentation: { profile: "receipt_80mm" },
-});
-
-const page = await timbro.fiscalDocuments.list({ limit: 20 });
-
-const numbering = await timbro.fiscalNumbering.getReadiness();
-const type31 = numbering.documents.e31;
-const custody = await timbro.certificateCustody.getReadiness();
-```
-
-The repository includes complete, runnable issuance examples for both supported integration styles:
-
-- [`examples/fiscal-document.ts`](examples/fiscal-document.ts) uses the typed SDK
-- [`examples/fiscal_document.py`](examples/fiscal_document.py) uses Python's standard-library HTTP client and the raw snake-case wire contract
-
-Set `TIMBRO_BASE_URL`, `TIMBRO_CREDENTIAL`, and a unique `TIMBRO_SOURCE_ID` before running either
-example. `TIMBRO_SOURCE_VERSION` defaults to `v1`. Run the TypeScript example with
-`node packages/sdk/examples/fiscal-document.ts` on the repository's Node 24 runtime, or run the
-Python example with `python3 packages/sdk/examples/fiscal_document.py`. Use a Source connection in
-the intended fiscal environment because either command submits an issuance task.
-
-The immutable Source identity is the `{ id, version }` tuple; `version` is an opaque trimmed string chosen by the Source system. Timbro computes and retains the canonical digest internally. The caller does not send a digest or an idempotency header. Repeating an older tuple recovers its original operation even after another version becomes current.
-
-To replace a request rejected before numbering, submit corrected content with a new Source version and `predecessorOperationId` set to the rejected operation's `fiscalOperationId`. The predecessor must still be current. An accepted document requires a separate legal correction; an unknown outcome requires reconciliation. After authority rejection, replacement also requires the existing administrator authorization. A missing or stale predecessor returns `source_predecessor_conflict` without issuing again.
-
-Inspect `operation.outcome.outcome`, `operation.signedDocument.status` and `operation.printedRepresentation.status` independently. Authority acceptance can precede XML/PDF availability. The SDK preserves these owning-contract facts and exposes no derived top-level `status` or `issued` shortcut. Both immediate and pending admission responses return the resource. [Spanish retry and recovery guide](../../docs/integrations/source-submission-recovery.md)
-
-`fiscalDocuments.issue` is the one issuance task for ordinary documents and corrections. A
-correction names both the affected Timbro operation and the original Source identity explicitly:
-
-```ts
-await timbro.fiscalDocuments.issue({
-  source: { id: "odoo-credit-1002", version: "v1" },
-  action: {
-    kind: "creditNote",
-    correction: "correctAmounts",
-    affectedFiscalOperationId: original.fiscalOperationId,
-    originalSource: { id: "odoo-invoice-1001", version: "v3" },
-    reason: "The taxable amount was corrected",
-  },
-  document,
-  numberingInstruction: { kind: "centralAssignment" },
-  printedRepresentation: { profile: "a4" },
-});
-```
-
-All issuance task boundaries return a retained operation when fiscal evaluation rejects it; inspect `operation.outcome` and its diagnostics just as you would after `get` or a webhook. Exceptions remain reserved for malformed or unsupported input, authentication and authorization failures, conflicts, transport failures, and other cases where no modeled result can be returned.
-
-`fiscalDocuments.get({ fiscalOperationId })` recovers an operation and its actor-facing outcome, returning `undefined` for a typed not-found response. `fiscalDocuments.findBySource({ source: { id, version } })` arbitrates by the caller's source identity. Public resources use camelCase, keep every amount as an exact decimal string, and expose `fiscalOperationId` separately from the fiscal authority identity (`outcome.fiscalIdentity`) and its fiscal number. The status vocabulary preserves `requested`, `processing`, `delayed`, `unavailable`, `verifying`, `issued`, `rejected`, and `actionRequired`. Fiscal numbering and certificate-custody readiness are separate tasks from issuance, and artifact retrieval is exposed through `fiscalArtifacts`.
-
-`fiscalDocuments.getTiming({ fiscalOperationId })` returns the bounded diagnostic projection of timing contract version 4. `stages` names each step of the operation as a `TimingStageId` occurrence with its clock, bound, duration, and exclusive time; `TIMING_STAGE_IDS` lists every published id. `workClaims` lists each executing claim on the operation's work, `drainRuns` the drains that made those claims, and `readAt` is Timbro's database clock at the read, so a reader on another clock can measure its skew. These fields are optional in the types: a version 3 report still parses and carries none of them, so branch on `timingContractVersion`. The row lists name work `dueToSettlementMs` and Webhook `queuedToSettlementMs` by their endpoints, and expose `fiscalDeliveries`, `fiscalDeliveryAttempts`, and `fiscalDeliveryEvents` so `submitted`, `delivered`, and `bounced` remain distinct. `attemptDurationMs` measures the stamp-side interval from delivery claim through recorded settlement, including local preparation; it does not isolate provider time. Event rows correlate through `fiscalDeliveryId`, and their provider-created and stamp-received times remain separate. The report omits recipient addresses and provider identifiers.
-
-When `operation.signedDocument.status` is `ready`, its `artifactKind` is `signed_complete_document` and its `artifactId` identifies the immutable artifact. Retrieve and verify it with `fiscalArtifacts.downloadSignedDocument({ fiscalOperationId: operation.fiscalOperationId })`.
-
-An `outcome_unknown` submission remains `pending` while Timbro reconciles the same fiscal identity with DGII. Continue observing it without resubmitting the document. Only `intervention_required` means automatic reconciliation exhausted its bounded budget and an operator must take over.
-
-`fiscalArtifacts.downloadPrintedRepresentation({ fiscalOperationId })` retrieves the operation-addressed immutable PDF and verifies every published identity header, profile/version, renderer identity, digest, signed-source digest, pagination-plan digest, length, page count, creation time, media type, and the actual bytes. The result exposes one content digest as `contentSha256`; storage keys and compatibility aliases are not exposed.
-
-### Share an already-issued receipt
-
-An issuing Source can share an accepted operation without issuing another invoice or sending email. Keep the returned reference in protected server-side storage and pass it through an authenticated service handoff:
-
-```ts
-const receipt = await issuer.fiscalDocuments.shareReceipt({ fiscalOperationId });
-const metadata = await receiver.fiscalReceipts.get({ receipt });
-if (metadata?.printedRepresentation.status === "ready") {
-  const pdf = await receiver.fiscalReceipts.downloadPrintedRepresentation({ receipt });
-  // Deliver pdf.bytes through the receiving service's authorized receipt route.
+const timbro = createTimbroInvoices({ apiKey });
+const request = {
+  invoiceReference: "sale-123",
+  type: "E32",
+  currency: "DOP",
+  incomeType: "01",
+  paymentTerms: { type: "immediate" },
+  items: [{
+    description: "Servicio",
+    quantity: "1",
+    unit: "unit",
+    kind: "service",
+    unitPrice: "1250.00",
+    tax: { kind: "itbis_18", included: true },
+  }],
+} satisfies InvoiceRequest;
+
+const invoice = await timbro.invoices.create(request);
+const current = await timbro.invoices.retrieve(invoice.id);
+if (current?.files.pdf.status === "ready") {
+  const pdf = await timbro.invoices.downloadPdf(current.id);
+  // Send pdf.bytes through your application's authorized download route.
 }
 ```
 
-Both clients use the existing `createTimbroClient` setup. Receipt reads apply only the reference's bearer token, even if the receiving client normally uses workload authentication. The receiver obtains the verified issuer RNC, environment, Source revision, fiscal identity, DOP totals, acceptance timestamp, and PDF readiness. It receives neither XML nor diagnostics. A missing or revoked receipt returns `undefined`; a pending PDF returns `fiscal_artifact_not_found`. Use the [Spanish receipt guide](../../docs/integrations/source-receipts.md) for handoff and payment checks.
-
-Source credentials can also operate the received-document namespace. The server infers the
-Organization, Legal issuer, and Fiscal environment from that credential, so the list cannot be
-widened with a tenant or issuer path parameter:
+For a hosted Gateway deployment, the same configured origin and API key also expose Business setup and WebhookEndpoint operations. Use `mode: "test"` or `"live"` for environment-specific setup and key issuance; sending a TesteCF invoice is a separate test-only operation.
 
 ```ts
-const received = await timbro.receivedDocuments.list({ limit: 50, recovery: "pending" });
-const document = await timbro.receivedDocuments.get({
-  fiscalReceptionId: received.data[0].fiscalReceptionId,
-});
-await timbro.receivedDocuments.respond({
-  fiscalReceptionId: document.summary.fiscalReceptionId,
-  response: { decision: "accepted" },
+const business = await timbro.business.retrieve();
+await timbro.business.configureInvoicing({
+  mode: "test",
+  idempotencyKey: "configure-invoicing-test-1",
 });
-const signedXml = await timbro.receivedDocuments.downloadSignedDocument({
-  fiscalReceptionId: document.summary.fiscalReceptionId,
+const testInvoice = await timbro.business.issueTestInvoice();
+const invoiceKey = await timbro.business.issueInvoiceKey({
+  mode: "test",
+  idempotencyKey: "issue-invoice-key-test-1",
 });
-```
-
-`receivedDocuments.respond` accepts `accepted` or `rejected` with a non-blank `motive` for a
-rejected response; an exact
-replay returns the recorded response and a changed decision or motive raises a conflict. The
-downloaded XML is retained inbound evidence and the SDK verifies its media type, length, and
-SHA-256 digest. If the Evidence Vault is unavailable, the download returns the typed
-`fiscal_artifact_unavailable` problem with HTTP 503.
 
-Buyer delivery is independent of representation readiness:
-
-```ts
-const delivery = await timbro.fiscalDeliveries.create({
-  fiscalOperationId: operation.fiscalOperationId,
-  recipientEmail: "buyer@example.test",
-  accountClaimUrl: "https://checkout.example.test/account?receipt=order-1001",
-  idempotencyKey: "checkout-order-1001-email",
+const endpoint = await timbro.webhookEndpoints.create({
+  url: "https://merchant.example/webhooks/timbro",
+  enabledEvents: ["invoice.accepted", "invoice.rejected", "invoice.operatorRequired", "invoice.ready"],
+  idempotencyKey: "create-invoice-webhook-1",
+});
+const deliveries = await timbro.webhookEndpoints.listDeliveries({
+  webhookEndpointId: endpoint.id,
+  limit: 50,
 });
+if (deliveries.hasMore && deliveries.nextCursor !== null) {
+  const nextPage = await timbro.webhookEndpoints.listDeliveries({
+    webhookEndpointId: endpoint.id,
+    limit: 50,
+    cursor: deliveries.nextCursor,
+  });
+}
 ```
 
-The email is in Spanish and names the Legal issuer and the e-NCF. `accountClaimUrl` is optional;
-when present, the email also offers "Guardar en Cuenta Timbro" with that `https` URL. The URL
-grants nothing by itself, because delivery emails are often forwarded.
+`business.retrieve` returns current capabilities, setup status, and requirements. Update only the business members being replaced with `business.update`; import a signing certificate with `business.importSigningCertificate`; and read the business again to confirm retained state. `issueTestInvoice` always uses the test environment. Invoice API keys are issued for one explicit mode and returned once. The Gateway enforces credential authority for each task.
 
-### Webhooks and recovery
+Webhook endpoints support list, create, retrieve, delete, delivery listing, event replay, secret rotation, suspension, and reactivation. Lists return `data`, `hasMore`, and `nextCursor`; pass the cursor to the next page with the same filters. Delivery `eventType` remains a string so stored deliveries from earlier event contracts can still be read. Use a Gateway host for these hosted controls; native Source origins expose their Source operations separately.
 
-An approved direct Source registers its HTTPS callback with the same scoped credential:
+Persist the request and its `invoiceReference` before submitting it. An equivalent retry returns the same retained Invoice ID and current state. Changed content under that reference returns `invoice_reference_conflict`. An optional `idempotencyKey` in the second argument binds a command independently of the reference. A timeout or lost response does not justify a new reference or a second invoice.
 
-```ts
-const registration = await timbro.webhooks.register({
-  url: "https://erp.example.com/timbro/webhook",
-  idempotencyKey: "odoo-company-42-callback-v1",
-});
-```
+For ERP attribution, the optional `source: {id, version}` identifies the immutable accounting snapshot. When omitted, the reference supplies the source identity and the version is `initial`. Odoo keeps ownership of its posted accounting facts, prepared requests, and durable retry work.
 
-Persist that key before setup, and store `registration.signingSecret` in your server's secret
-store. The exact key and body recover the same endpoint and original secret for 24 hours while
-the endpoint remains active and unrotated. Later retries return the endpoint with a null secret;
-they never issue another secret. A different registration key or changed body returns a conflict.
-Hosted and provider-managed callbacks retain their own setup lifecycle.
+Amounts are exact decimal strings. `unitPrice` is interpreted using the item's `tax.included` flag. `incomeType` is explicit when supplied; otherwise the issuer's configured default must exist. A create request may supply `expectedTotals` to assert accounting agreement. A mismatch refuses admission without consuming a fiscal number.
 
-The complete `node packages/sdk/examples/register-webhook.ts` example reads `TIMBRO_BASE_URL`,
-`TIMBRO_CREDENTIAL`, `TIMBRO_CALLBACK_URL`, `TIMBRO_CALLBACK_REGISTRATION_KEY`, and
-`TIMBRO_WEBHOOK_SECRET_FILE`. It saves the secret in a private file and prints only endpoint
-metadata. See [Recibe avisos del e-CF](../../docs/integrations/source-webhooks.md) for setup and recovery.
+The request is discriminated by `type`. E31 and E32 have sales fields, E41 has supplier and withholding fields, and E45 has buyer and government eligibility fields. They use the same methods and Invoice identity.
 
-After a receiver outage, inspect `webhookDeliveries.list` for pending or dead-letter deliveries
-and replay selected retained fiscal events:
+An optional preview evaluates the request without creating an Invoice, reserving a number, or producing files:
 
 ```ts
-const replay = await timbro.webhooks.replay({
-  webhookEndpointId: registration.webhookEndpoint.id,
-  eventIds: [delivery.webhook_event_id],
-  idempotencyKey: "odoo-company-42-replay-20261001",
-});
+const preview = await timbro.invoices.preview(request);
+if (preview.status === "invalid") {
+  for (const problem of preview.problems) {
+    console.error(problem.path, problem.message);
+  }
+}
 ```
 
-Persist the key and selection first. An exact retry returns the same `webhookReplayId` without
-creating another delivery. Replay preserves the original event ID, sequence, and payload;
-deduplicate it alongside automatic retries. Select 1–100 outbound fiscal events from your Source.
-Supplier reception events are outside this method's scope.
+`status` describes fiscal progress. `processing` and `verifying` retain the same identity while work continues. Acceptance, file readiness, buyer delivery readiness, and payment success are separate facts. `latestEvent` is null until a real notification has been retained. Do not use file availability or the latest notification timestamp as authority acceptance evidence.
 
-The complete `node packages/sdk/examples/replay-webhook.ts` example reads `TIMBRO_BASE_URL`,
-`TIMBRO_CREDENTIAL`, `TIMBRO_WEBHOOK_ENDPOINT_ID`, comma-separated `TIMBRO_WEBHOOK_EVENT_IDS`,
-and `TIMBRO_WEBHOOK_REPLAY_KEY`. It prints replay metadata only.
-
-Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) contract. Each request
-carries `webhook-id`, `webhook-timestamp`, and `webhook-signature`, and the signature covers
-`<webhook-id>.<webhook-timestamp>.<body>`. Verify it against the exact request body bytes before
-parsing. Do not parse, reserialize, or pretty-print the body first; the signed payload is the
-original UTF-8 text.
-
-`webhooks.verify` checks the headers and returns the typed event, so a receiver never parses an
-unverified body:
+Replace a retained Invoice after authority rejection by sending a new canonical request. The replacement keeps the predecessor's Source ID, uses a new Source version and `invoiceReference`, and returns a new Invoice whose `replacesInvoiceId` identifies the predecessor. A `422` admission refusal has no retained Invoice ID, so correct the request and call `create`; `replace` applies only to a retained, replaceable Invoice. Authority-rejected numbering gaps still require the existing administrator authorization.
 
 ```ts
-const event = await timbro.webhooks.verify({
-  body: requestBodyText,
-  headers: Object.fromEntries(request.headers),
-  secret: webhookSecret,
+const replacement = await timbro.invoices.replace(rejectedInvoice.id, {
+  ...request,
+  invoiceReference: "sale-123-r1",
 });
-if (event.type === "source_connection.verification_requested") {
-  // Build and submit the signed activation proof before acknowledging this event.
-  // See examples/webhook-receiver.ts for the complete server-runtime flow.
-  throw new Error("activation verification must complete before acknowledgement");
-}
-const recovered =
-  event.type === "fiscal_reception.received" || event.type === "fiscal_reception.not_received"
-    ? undefined
-    : await timbro.fiscalDocuments.get({ fiscalOperationId: event.data.fiscal_operation_id });
 ```
 
-The operation's `source.id` and `source.version` identify the caller's retained invoice even if
-the callback arrives before the caller records the issuance response. Retrieve current state
-under the same Source credential, then apply it to that invoice through your existing processor.
+`downloadXml` and `downloadPdf` return verified bytes, SHA-256, byte length, creation time, and Invoice identity. PDF downloads also verify the signed source, eNCF, type, layout, and page count. Both methods accept an optional `signal`; create, preview, retrieve, and list do too. A download refuses mismatched bytes or identity.
 
-A rejected delivery throws `WebhookVerificationError`, whose `rejection` names the cause:
-`invalid_secret`, `missing_header`, `malformed_header`, `stale_timestamp`, `future_timestamp`,
-`signature_mismatch`, `unreadable_envelope`, or `id_mismatch`. Answer a delivery you cannot trust
-with a 4xx and no side effect. `invalid_secret` is the one exception: the secret you configured is
-unusable, the delivery itself is intact, so answer 500 and let Timbro retry the event while you
-repair the secret.
+Recover by ID or retained reference:
 
 ```ts
-import { WebhookVerificationError } from "@timbro/invoices";
-
-try {
-  await timbro.webhooks.verify({ body, headers, secrets: [nextSecret, retiredSecret] });
-} catch (cause) {
-  if (cause instanceof WebhookVerificationError) {
-    return new Response(cause.rejection, {
-      status: cause.rejection === "invalid_secret" ? 500 : 400,
-    });
-  }
-  throw cause;
+const page = await timbro.invoices.list({ invoiceReference: request.invoiceReference });
+const retained = page.data[0];
+if (retained !== undefined) {
+  const current = await timbro.invoices.retrieve(retained.id);
 }
 ```
 
-The signing secret is issued as `whsec_<base64>`; the HMAC key is the base64-decoded remainder, and
-a secret that is not that shape is rejected rather than used as literal bytes. `webhook-signature`
-carries one space-separated `v1,` entry per valid secret, and a delivery is verified when any entry
-matches any secret you hold. A timestamp more than five minutes from the receiver's clock is refused
-in both directions. `verify` refuses a delivery whose `webhook-id` is not the envelope `id`, and
-that id is the key you deduplicate on. `sequence` stays a decimal string so JavaScript cannot lose
-bigint precision. If an operation-event delivery is missed, recover the current actor-facing outcome
-with `fiscalDocuments.get` using its operation ID.
+`retrieve` returns `undefined` only for `invoice_not_found`. Lists return one page with `data`, `hasMore`, and `nextCursor`. Pass the returned cursor to the next list call, with the same credential and filters. The default limit is 20, with a maximum of 100.
+
+API refusals use `InvoiceError`, with `code`, `status`, `requestId`, `problems`, and `isRetryable`. Malformed input is validated against the generated contract before submission. Preserve the original request when retrying a transport failure; resolve permanent validation and conflict errors before submitting corrected work.
 
-Every public list returns one page: `object: list`, `data`, `hasMore`, and an opaque `nextCursor`
-bound to the Organization and the list that minted it, down to the Webhook endpoint for a
-delivery cursor.
-Presenting a cursor anywhere else answers 400 `invalid_collection_cursor`. `limit` accepts 1 to
-100 and defaults to 20, and a multi-value filter repeats its parameter. `list` returns a single
-page, while `listAll` follows every cursor for you:
+Verify webhook signatures over the exact request body, then retrieve current state:
 
 ```ts
-const page = await timbro.webhookDeliveries.list({
-  webhookEndpointId,
-  states: ["pending", "dead_lettered"],
-  limit: 50,
+const event = await timbro.webhooks.verify({
+  body: await httpRequest.text(),
+  headers: Object.fromEntries(httpRequest.headers),
+  secrets: [currentWebhookSecret, previousWebhookSecret],
 });
-
-for await (const delivery of timbro.webhookDeliveries.listAll({ webhookEndpointId })) {
-  await reconcile(delivery);
+if (
+  event.type === "invoice.accepted" ||
+  event.type === "invoice.rejected" ||
+  event.type === "invoice.operatorRequired" ||
+  event.type === "invoice.ready"
+) {
+  const current = await timbro.invoices.retrieve(event.data.id);
 }
 ```
 
-`webhookDeliveries`, `fiscalDocuments`, and `receivedDocuments` are the credential-scoped lists this
-client wraps. The operation timeline is read with a Workspace session instead of a credential,
-so a Workspace consumer reads those pages through its own session-authenticated request and walks
-them with the exported `walkCollectionPages`:
+Register the receiving endpoint through the hosting service's webhook endpoint API. All invoice types share these four event types. `invoice.ready` means a positive authority outcome and retained XML/PDF files; it does not promise payment or email delivery. A notification can arrive before create returns. Match the recovered reference and source coordinates, and apply it through your existing durable processor.
 
-```ts
-import { walkCollectionPages } from "@timbro/invoices";
-import { zWorkspaceFiscalOperationPage } from "@timbro/invoices/generated";
-
-for await (const operation of walkCollectionPages(async (cursor) => {
-  const query = cursor === undefined ? "?limit=100" : `?limit=100&cursor=${cursor}`;
-  const response = await fetch(
-    `${stampServerOrigin}/v1/organizations/${organizationId}/fiscal-operations${query}`,
-    { credentials: "include" },
-  );
-  return zWorkspaceFiscalOperationPage.parse(await response.json());
-})) {
-  await render(operation);
-}
-```
+Deduplicate notifications by `event.id`. `data.id` identifies the Invoice, and `sequence` stays a decimal string. Verification accepts any configured rotation secret and rejects invalid signatures, stale timestamps, malformed envelopes, and mismatched event IDs. It throws `WebhookVerificationError` with a specific `rejection`. An unusable configured secret requires receiver recovery; no rejected delivery should cause an application side effect.
 
-The walk throws a `FiscalError` when a page reports more resources without a cursor to resume
-from, or returns the cursor it was read with, because neither page can be walked to the end of
-the list.
+Rust owns the Invoice wire schemas, and the SDK generates its public types and boundary validators from them. The SDK does not persist business work or replace ERP accounting. Source registration, restricted receipt sharing, supplier reception, and operational diagnostics retain their own scoped tasks. Local SDK checks do not establish hosted behavior, DGII qualification, or provider certification.
 
-Credentials belong on a trusted application server or native-assisted client. The package does not establish DGII approval, printer compatibility or legibility, hosted Checkout cutover, production capacity, or certification.
+Administration and installation tooling use `@timbro/invoices/admin`. Source snapshots, custody transports, workload bindings, and operation timing do not appear in the ordinary package root. The public `createTimbroInvoices` call accepts the API key and optional origin; Invoice creation does not require assembling those administrative clients.

package/dist/admin.d.ts

@@ -0,0 +1,44 @@
+export type { CertificateCustodyImportCommand, CertificateCustodyImportResult, } from "./certificate-custody-import.ts";
+export type { CertificateCustodyReadiness } from "./certificate-custody-readiness.ts";
+export type { CollectionPage } from "./collection.ts";
+export { walkCollectionPages } from "./collection.ts";
+export type { DirectConnectionApproval, DirectConnectionApprovalCommand, DirectConnectionClient, DirectConnectionClientOptions, DirectConnectionConfirmation, DirectConnectionCreateCommand, DirectConnectionEnvironment, DirectConnectionPoll, DirectConnectionPreview, DirectConnectionRequest, DirectConnectionRequestCommand, } from "./direct-connection.ts";
+export { createDirectConnectionClient, generateDirectConnectionCredential, } from "./direct-connection.ts";
+export type { FiscalNumberingReadiness } from "./fiscal-numbering-readiness.ts";
+export type { FiscalDocument, FiscalDocumentAction, FiscalDocumentIssueCommand, FiscalDocumentListCommand, FiscalDocumentNumberingInstruction, FiscalDocumentPage, FiscalOperationResource, FiscalOriginalSource, FiscalSource, HostedFiscalTenant, SourceType31Snapshot, SourceType32Snapshot, SourceType33Snapshot, SourceType34Snapshot, SourceType41Snapshot, SourceType43Snapshot, SourceType44Snapshot, SourceType45Snapshot, SourceType46Snapshot, SourceType47Snapshot, } from "./fiscal-operation.ts";
+export { toFiscalDocumentSnapshot } from "./fiscal-operation.ts";
+export type { FiscalOperationTimingReport, TimingStageId } from "./fiscal-operation-timing.ts";
+export { TIMING_STAGE_IDS } from "./fiscal-operation-timing.ts";
+export type { FiscalOperationOutcomeResource, InvoiceDeliveryResource, InvoicePage, InvoicePreview, InvoiceReceipt, InvoiceReceiptAccess, InvoiceRequest, InvoiceResource, InvoiceType, PrintedRepresentationProfile, SourceCreditNoteCorrection, SourceDebitNoteCorrection, SourceFiscalAction, WebhookDelivery, WebhookDeliveryPage, WebhookDeliveryState, } from "./generated/index.ts";
+export type { HostedTenant, HostedTenantClient, HostedTenantClientOptions, HostedTenantCreateCommand, HostedTenantEnvironment, HostedTenantRelease, HostedTenantReleaseCommand, HostedTenantWebhookSecretRotationCommand, HostedWebhookSecretRotation, } from "./hosted-tenant.ts";
+export { createHostedTenantClient } from "./hosted-tenant.ts";
+export type { HostedWorkspaceTransportOptions } from "./hosted-workspace-transport.ts";
+export { createHostedWorkspaceTransport } from "./hosted-workspace-transport.ts";
+export type { InvoiceCreateOptions, InvoiceDeliveryCommand, InvoiceDeliveryReadCommand, InvoiceListFilters, InvoicePdfDownload, InvoiceReplacement, InvoiceRequestOptions, InvoiceXmlDownload, TimbroInvoices, TimbroInvoicesOptions, } from "./invoice.ts";
+export { createTimbroInvoices, verifyInvoicePdfDownload, verifyInvoiceXmlDownload, } from "./invoice.ts";
+export type { InvoiceErrorDetail, InvoiceFailure } from "./invoice-error.ts";
+export { InvoiceError } from "./invoice-error.ts";
+export type { BusinessConfigureInvoicingCommand, BusinessImportSigningCertificateCommand, BusinessIssueInvoiceKeyCommand, BusinessIssueTestInvoiceCommand, BusinessIssueTestInvoiceOptions, BusinessUpdateCommand, InvoiceHostedControls, WebhookEndpointCreateCommand, WebhookEndpointListDeliveriesCommand, WebhookEndpointListFilters, WebhookEndpointReplayCommand, } from "./invoice-hosted-controls.ts";
+export type { PrintedRepresentationDownload } from "./printed-representation.ts";
+export type { ProblemBody, ProblemCatalogEntry, ProblemCode, ProblemFailure, PublicProblemCode, } from "./problem-contract.ts";
+export { PROBLEM_CATALOG } from "./problem-contract.ts";
+export { toWireCase } from "./public-case.ts";
+export type { CommercialResponse, ReceivedDocumentDownload, ReceivedDocumentListCommand, ReceivedDocumentPage, ReceivedDocumentRecoveryFilter, ReceivedDocumentResource, ReceivedDocumentResponseFilter, ReceivedDocumentStateFilter, ReceivedDocumentSummary, } from "./received-documents.ts";
+export { verifyReceivedDocumentXmlDownload } from "./received-documents.ts";
+export { digestSha256Hex } from "./sha256.ts";
+export type { SignedDocumentDownload } from "./signed-document.ts";
+export type { HostedInvoiceCredential, HostedInvoiceCredentialIssueCommand, SourceConnectionActivationVerificationCommand, } from "./source-connection.ts";
+export type { SourceConnectionTransportOptions } from "./source-connection-transport.ts";
+export type { StampServerBearerTokenProvider, StampServerHttpAuthentication, } from "./stamp-server-http-transport.ts";
+export type { TimbroClient, TimbroClientAuthentication, TimbroClientOptions, } from "./timbro-client.ts";
+export { createTimbroClient } from "./timbro-client.ts";
+export type { WebhookDeliveryListCommand } from "./webhook-delivery.ts";
+export type { DeliveredWebhookEvent, InvoiceWebhookEvent, InvoiceWebhookEventEnvelope, ReceptionWebhookEvent, WebhookEvent, } from "./webhook-event.ts";
+export { parseDeliveredWebhookEvent, parseWebhookEvent, } from "./webhook-event.ts";
+export type { WebhookRegistration, WebhookRegistrationCommand } from "./webhook-registration.ts";
+export type { WebhookReplay, WebhookReplayCommand } from "./webhook-replay.ts";
+export type { WebhookDeliveryHeaders, WebhookVerificationCommand, WebhookVerificationRejection, } from "./webhook-verification.ts";
+export { verifyWebhookDelivery, WebhookVerificationError } from "./webhook-verification.ts";
+export type { WorkspaceClient, WorkspaceClientOptions } from "./workspace.ts";
+export { createWorkspaceClient } from "./workspace.ts";
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"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"}

package/dist/admin.js

@@ -0,0 +1,16 @@
+export { walkCollectionPages } from "./collection.js";
+export { createDirectConnectionClient, generateDirectConnectionCredential, } from "./direct-connection.js";
+export { toFiscalDocumentSnapshot } from "./fiscal-operation.js";
+export { TIMING_STAGE_IDS } from "./fiscal-operation-timing.js";
+export { createHostedTenantClient } from "./hosted-tenant.js";
+export { createHostedWorkspaceTransport } from "./hosted-workspace-transport.js";
+export { createTimbroInvoices, verifyInvoicePdfDownload, verifyInvoiceXmlDownload, } from "./invoice.js";
+export { InvoiceError } from "./invoice-error.js";
+export { PROBLEM_CATALOG } from "./problem-contract.js";
+export { toWireCase } from "./public-case.js";
+export { verifyReceivedDocumentXmlDownload } from "./received-documents.js";
+export { digestSha256Hex } from "./sha256.js";
+export { createTimbroClient } from "./timbro-client.js";
+export { parseDeliveredWebhookEvent, parseWebhookEvent, } from "./webhook-event.js";
+export { verifyWebhookDelivery, WebhookVerificationError } from "./webhook-verification.js";
+export { createWorkspaceClient } from "./workspace.js";

package/dist/certificate-custody-import.d.ts

@@ -1,11 +1,13 @@
 import type { HostedFiscalTenant } from "./fiscal-operation.ts";
-import { type HostedImportResponse } from "./generated/index.ts";
+import { type HostedImportRequest, type HostedImportResponse } from "./generated/index.ts";
 import type { Client } from "./generated-operation-client.ts";
 import { type ReadonlyCamelCase } from "./public-case.ts";
 export type CertificateCustodyImportCommand = {
     readonly certificateP12Base64: string;
     readonly password: string;
-    readonly hosted: Pick<HostedFiscalTenant, "checkoutTenantId"> & Partial<Pick<HostedFiscalTenant, "environment">>;
+    readonly hosted: Pick<HostedFiscalTenant, "checkoutTenantId"> & {
+        readonly environment?: NonNullable<HostedImportRequest["environment"]>;
+    };
     readonly signal?: AbortSignal;
 };
 export type CertificateCustodyImportResult = ReadonlyCamelCase<HostedImportResponse>;

package/dist/certificate-custody-import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"certificate-custody-import.d.ts","sourceRoot":"","sources":["../src/certificate-custody-import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,KAAK,oBAAoB,EAAkC,MAAM,sBAAsB,CAAC;AACjG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAE9D,OAAO,EAAE,KAAK,iBAAiB,EAAgB,MAAM,kBAAkB,CAAC;AAExE,MAAM,MAAM,+BAA+B,GAAG;IAC5C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,GAC3D,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;AAErF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,CAAC,CA0BzC"}
+{"version":3,"file":"certificate-custody-import.d.ts","sourceRoot":"","sources":["../src/certificate-custody-import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AAE9D,OAAO,EAAE,KAAK,iBAAiB,EAAgB,MAAM,kBAAkB,CAAC;AAExE,MAAM,MAAM,+BAA+B,GAAG;IAC5C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,kBAAkB,CAAC,GAAG;QAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC,CAAC;KACxE,CAAC;IACF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG,iBAAiB,CAAC,oBAAoB,CAAC,CAAC;AAErF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,CAAC,CA0BzC"}

package/dist/certificate-custody-import.js

@@ -1,4 +1,4 @@
-import { importHostedCertificateCustody } from "./generated/index.js";
+import { importHostedCertificateCustody, } from "./generated/index.js";
 import { throwGeneratedProblem } from "./generated-problem.js";
 import { toPublicCase } from "./public-case.js";
 export async function importHostedCertificateCustodyResource(client, command) {

package/dist/collection.d.ts

@@ -3,7 +3,7 @@ import { type CursorPage, type CursorPageWalkOptions } from "@timbro/protocol";
 export type CollectionPage<TResource> = CursorPage<TResource>;
 export type CollectionWalkOptions = CursorPageWalkOptions;
 /**
- * Yields every resource in a Collection, following `next_cursor` until `has_more` is false.
+ * Yields every resource in a Collection, following `nextCursor` until `hasMore` is false.
  *
  * A page that reports more resources without a cursor, or that returns the cursor it was read
  * with, cannot be walked to the end of the Collection, so the walk throws rather than stopping

package/dist/collection.js

@@ -1,7 +1,7 @@
 import { CursorPageWalkError, walkCursorPages, } from "@timbro/protocol";
-import { FiscalError } from "./fiscal-error.js";
+import { InvoiceError } from "./invoice-error.js";
 /**
- * Yields every resource in a Collection, following `next_cursor` until `has_more` is false.
+ * Yields every resource in a Collection, following `nextCursor` until `hasMore` is false.
  *
  * A page that reports more resources without a cursor, or that returns the cursor it was read
  * with, cannot be walked to the end of the Collection, so the walk throws rather than stopping
@@ -15,7 +15,7 @@ export async function* walkCollectionPages(readPage, options) {
         if (!(cause instanceof CursorPageWalkError)) {
             throw cause;
         }
-        // biome-ignore lint/style/useErrorCause: FiscalError already exposes the bounded protocol failure detail.
-        throw new FiscalError(cause.message, { failure: cause.rejection === "aborted" ? "cancelled" : "server_processing" }, { cause });
+        // biome-ignore lint/style/useErrorCause: InvoiceError already exposes the bounded protocol failure detail.
+        throw new InvoiceError(cause.message, { failure: cause.rejection === "aborted" ? "cancelled" : "server_processing" }, { cause });
     }
 }