@payclave/sdk-server 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @payclave/sdk-server
 
+## 0.3.0
+
+### Added
+
+- `checkInvoiceRefund`, which asks Payclave's refund policy whether a refund would be accepted before you send it.
+- `recordInvoiceRefundReference` accepts `destinationAddress` and `destinationReason`, and `externalTransactionHash` is optional (omit it in test mode). Refund adjustments include `verificationStatus`, `destinationAddress`, `destinationSource`, `riskFlags`, `senderAddress`, `verifiedAt`, `verificationFailureReason`, and `failedTransactionHash`.
+- `invoice.refund_verified` and `invoice.refund_failed` webhook event types.
+
+## 0.2.0
+
+### Changed
+
+- Requests time out after 30 seconds unless `timeoutMs` is set.
+
+### Added
+
+- Add typed rich-invoice draft creation, cursor listing, optimistic update, and issue methods.
+- Expand invoice responses with itemization, customer and seller snapshots, hosted-invoice fields, and checkout-session history.
+- Add exact-remainder recovery checkout, void, void-remaining, uncollectible, duplicate, and external refund-reference invoice methods.
+- Expand rich invoices with verified payment and adjustment timelines and collection-state webhooks.
+- Add typed payment-link create, list, retrieve, update, pause, resume, archive, duplicate, and linked-invoice methods.
+- Support retry-safe idempotency keys on invoice updates, invoice issue, and payment-link mutations.
+- Add invoice issue-email, resend, reminder scheduling, and durable delivery-history types and methods.
+- Add reviewed single-use payment-link reservation release and completion/expiry webhook events.
+- Add authenticated invoice PDF downloads with typed bytes, filename, and request ID.
+- Add typed reconciliation schema and bounded summary readers with date, status, token, and exception filters.
+- Add asynchronous reconciliation export create, list, retrieve, cancel, and authenticated streaming download helpers.
+- Add webhook delivery detail, timed attempt history, and immutable idempotent replay helpers.
+- Add typed webhook error categories, safe request/response evidence, and response-sanitization metadata.
+- Add webhook endpoint list, retrieve, update, archive, signing-secret rotation, overlap-ending, and incident read helpers.
+- Verify dual `v1` signatures during the 24-hour signing-secret overlap.
+
+### Fixed
+
+- Add raw-request-body remediation guidance to webhook signature errors.
+- Report the package version correctly in the SDK identification header.
+
 ## 0.1.1
 
 ### Fixed

package/README.md

@@ -6,12 +6,23 @@ Use this package from your backend with a Payclave secret key. Never expose `sk_
 
 Package name: [`@payclave/sdk-server`](https://www.npmjs.com/package/@payclave/sdk-server).
 
+## Complete merchant reference
+
+See the [TypeScript + Express reference application](https://github.com/ianmasae/Payclave/tree/main/examples/typescript-checkout)
+for a standalone test-mode integration with SQLite, persistent event deduplication,
+durable retries, and idempotent simulated fulfillment. It uses the published SDK.
+
+- [Creating checkouts with stable keys](https://github.com/ianmasae/Payclave/blob/main/examples/typescript-checkout/src/checkout/service.ts)
+- [Verifying raw-body webhook signatures and timestamps](https://github.com/ianmasae/Payclave/blob/main/examples/typescript-checkout/src/payclave/webhook.ts)
+- [Matching invoices and fulfilling orders once](https://github.com/ianmasae/Payclave/blob/main/examples/typescript-checkout/src/webhooks/processor.ts)
+- [Retrying durably after failures and restarts](https://github.com/ianmasae/Payclave/blob/main/examples/typescript-checkout/src/webhooks/worker.ts)
+
 ## Install
 
 ```bash
-npm install @payclave/sdk-server
+npm install @payclave/sdk-server@0.3.0
 # or
-bun add @payclave/sdk-server
+bun add @payclave/sdk-server@0.3.0
 ```
 
 ## Create a checkout session
@@ -51,18 +62,59 @@ export async function POST(request: Request) {
 | `secretKey`  | `string`                  | `sk_test_...` or `sk_live_...`. Required.                         |
 | `apiBaseUrl` | `string`                  | Override the API base URL. Defaults to `https://api.payclave.com`. |
 | `fetcher`    | `(url, init) => Response` | Custom fetch implementation for tests or custom runtimes.         |
-| `timeoutMs`  | `number`                  | Per-request timeout.                                              |
+| `timeoutMs`  | `number`                  | Per-request timeout in ms. Defaults to `30000`.                   |
 
 Returns typed helpers:
 
 - `createCheckoutSession(input)`
 - `getCheckoutSession(id)`
 - `createInvoice(input)`
+- `createInvoiceDraft(input)`
+- `listInvoices(input?)`
 - `getInvoice(id)`
+- `downloadInvoicePDF(id)`
+- `updateInvoiceDraft(id, input)`
+- `issueInvoice(id, input)`
+- `sendInvoice(id, input?)`
+- `remindInvoice(id, input?)`
+- `createInvoiceCheckoutSession(id, input?)`
+- `voidInvoice(id, input?)`
+- `voidInvoiceRemaining(id, input?)`
+- `markInvoiceUncollectible(id, input?)`
+- `duplicateInvoice(id, input?)`
+- `recordInvoiceRefundReference(id, input)`
+- `createPaymentLink(input)`
+- `listPaymentLinks(input?)`
+- `getPaymentLink(id)`
+- `updatePaymentLink(id, input)`
+- `pausePaymentLink(id, input?)`
+- `resumePaymentLink(id, input?)`
+- `archivePaymentLink(id, input?)`
+- `duplicatePaymentLink(id, input?)`
+- `releasePaymentLinkReservation(id, input)`
+- `listPaymentLinkPayments(id, input?)`
 - `getPayment(id)`
 - `createWebhookEndpoint(input)`
+- `listWebhookEndpoints(options?)`
+- `getWebhookEndpoint(id, options?)`
+- `updateWebhookEndpoint(id, input)`
+- `archiveWebhookEndpoint(id, input)`
+- `rotateWebhookSecret(id, input)`
+- `endWebhookSecretOverlap(id, input)`
 - `createTestWebhook(input)`
 - `listWebhookDeliveries(input?)`
+- `getWebhookDelivery(id, options?)`
+- `listWebhookDeliveryAttempts(id, options?)`
+- `replayWebhookDelivery(id, input)`
+- `listWebhookIncidents(input?)`
+- `getWebhookIncident(id, options?)`
+- `getReconciliationSchema(version?)`
+- `getReconciliationSummary(input)`
+- `createReconciliationExport(input)`
+- `listReconciliationExports(input?)`
+- `getReconciliationExport(id, options?)`
+- `cancelReconciliationExport(id, input?)`
+- `downloadReconciliationExport(id, options?)`
 
 ### Authentication
 
@@ -84,14 +136,145 @@ This SDK is for backend code only and sends `Authorization: Bearer sk_test_...`
 
 ### Invoice input
 
-`createInvoice` accepts `amount`, `externalReference`, `metadata`, `expiresInMinutes`, `idempotencyKey`, and `signal`. Reuse the same `idempotencyKey` only when retrying the same invoice creation request after a timeout, network failure, `RATE_LIMIT_EXCEEDED`, or 5xx response.
+`createInvoice` keeps the amount-only compatibility flow and accepts `amount`, `externalReference`, `metadata`, `expiresInMinutes`, `idempotencyKey`, and `signal`.
+
+For itemized invoices, create a draft, then issue the returned version:
+
+```ts
+const draft = await payclave.createInvoiceDraft({
+  customer: { name: "Ada Lovelace", email: "ada@example.com" },
+  lines: [
+    {
+      description: "Implementation",
+      quantity: "2.5",
+      unitAmount: "40",
+    },
+  ],
+  taxes: [{ label: "VAT", amount: "4.75" }],
+  dueAt: "2026-09-30T23:59:59Z",
+  idempotencyKey: "invoice_order_123",
+})
+
+const issued = await payclave.issueInvoice(draft.id, {
+  version: draft.version!,
+  send: true,
+  idempotencyKey: "invoice_order_123_issue",
+})
+```
+
+The server calculates line totals and invoice totals at the settlement token's 6-decimal scale. `updateInvoiceDraft` replaces editable commercial fields and requires the latest `version`; `listInvoices` supports `limit`, `startingAfter`, and `collectionState`. Set `reminderSchedule` on the draft to schedule conservative before-due, due-date, and after-due reminders. Passing `send: true` to `issueInvoice` queues the issue email in the same durable workflow; `sendInvoice` resends it and `remindInvoice` queues a manual payment reminder. Invoice detail responses include immutable delivery history and the next scheduled reminder.
+
+For a partially paid invoice, `createInvoiceCheckoutSession` creates or reuses a checkout for the exact server-calculated remainder. Collection actions never move funds: `voidInvoiceRemaining` records the unpaid remainder as a write-off, and `recordInvoiceRefundReference` records a refund you sent, from your settlement wallet or another wallet such as an exchange account; Payclave never sends refunds. Call `checkInvoiceRefund` first: it reports whether the refund is allowed, whether it needs a `destinationReason`, and any warnings, such as a destination that is not the wallet the customer paid from or a refund of an overpayment. Where refund verification is available (always in test mode), the recorded adjustment starts as `verificationStatus: "pending"`, and Payclave verifies the transfer onchain before sending `invoice.refund_verified` or `invoice.refund_failed`. Issued invoice responses include all checkout sessions, independently verified payments, and adjustment records.
+
+`downloadInvoicePDF(id)` returns authenticated PDF bytes, a safe filename, and the request ID. The PDF is generated from the API's current server-side invoice snapshot; save or stream the returned bytes from trusted backend code.
+
+Reuse the same `idempotencyKey` only when retrying the same mutation after a timeout, network failure, `RATE_LIMIT_EXCEEDED`, or 5xx response.
+
+### Payment links
+
+Create a fixed or customer-entered public payment page from trusted server code:
+
+```ts
+const link = await payclave.createPaymentLink({
+  title: "Consulting deposit",
+  amountType: "fixed",
+  amount: "250.00",
+  currencyCode: "USDT",
+  usageType: "single_use",
+  collect: { email: true, reference: true },
+  successUrl: "https://merchant.example/orders/paid",
+  idempotencyKey: "consulting_deposit_123",
+})
+
+console.log(link.url)
+```
+
+Payment links inherit the settlement wallet, Polygon network, and USDC or USDT token selected for the secret key's mode. Amounts use decimal strings with no more than 6 fractional digits. A live `successUrl` or `cancelUrl` must use HTTPS and match the merchant's reviewed website origin.
+
+`updatePaymentLink` requires the latest `version`. Lifecycle and duplicate methods accept optional `idempotencyKey` and `signal` fields. `listPaymentLinks` supports cursor pagination plus status, amount type, usage type, currency, text, and UTC creation-time filters. `listPaymentLinkPayments` returns the invoices created from that link; the invoice and its independently verified payment records remain the source of payment truth.
+
+Single-use links reserve one invoice atomically. After reviewing the late-payment warning and confirming that no payment evidence remains unresolved, an owner or admin can call `releasePaymentLinkReservation(id, { acknowledgeLatePaymentRisk: true })`. Payclave voids the original invoice before reopening the link so two collectible invoices cannot exist at once.
+
+### Reconciliation
+
+Finance integrations can read the versioned data dictionary and a bounded summary without buffering export files:
+
+```ts
+const schema = await payclave.getReconciliationSchema()
+const summary = await payclave.getReconciliationSummary({
+  dateBasis: "invoice_created",
+  from: "2026-07-01T00:00:00Z",
+  to: "2026-08-01T00:00:00Z",
+  timezone: "Africa/Nairobi",
+  settlementTokens: ["USDT", "USDC"],
+  exceptionOnly: false,
+})
+
+console.log(schema.schemaVersion, summary.summaryByToken)
+```
+
+The interval is half-open (`from <= timestamp < to`) and may span at most 366 days. Amount totals are decimal strings grouped by chain and token contract; the SDK never adds USDC and USDT together. A summary includes the server cutoff, row counts, warnings, and bounded exception records.
+
+For a complete immutable pack, queue an export, poll its status, then consume the authenticated archive as a stream:
+
+```ts
+const queued = await payclave.createReconciliationExport({
+  format: "csv",
+  dateBasis: "invoice_created",
+  from: "2026-07-01T00:00:00Z",
+  to: "2026-08-01T00:00:00Z",
+  timezone: "Africa/Nairobi",
+  settlementTokens: ["USDT", "USDC"],
+  idempotencyKey: "reconciliation-2026-07",
+})
+
+let current = queued
+while (current.status === "queued" || current.status === "running") {
+  await new Promise((resolve) => setTimeout(resolve, 2_000))
+  current = await payclave.getReconciliationExport(queued.id)
+}
+
+if (current.status === "ready") {
+  const archive = await payclave.downloadReconciliationExport(current.id)
+  // Pipe archive.stream to durable storage without buffering the whole file.
+  console.log(archive.filename, archive.sha256)
+}
+```
+
+The archive contains the versioned manifest, token-separated summary, invoice, payment, onchain transaction, webhook delivery, and adjustment files. Downloads are authorized at request time. Payer-wallet PII is excluded by default; the public secret-key workflow does not bypass the separate elevated-permission and step-up requirement.
 
 ### Webhook endpoints
 
-`createWebhookEndpoint` accepts a `url`, optional `eventTypes`, and `signal`. Supported event types are exported as `PAYCLAVE_WEBHOOK_EVENT_TYPES` and currently include `invoice.paid`, `invoice.expired`, `payment.failed`, `payment.underpaid`, and `payment.overpaid`.
+`createWebhookEndpoint` accepts a `url`, optional `eventTypes`, and `signal`. Supported event types are exported as `PAYCLAVE_WEBHOOK_EVENT_TYPES` and include invoice issue, paid, partial, past-due, overpayment, void, uncollectible, refund recorded, verified, and failed, expiry, late payment after collection closure, payment-link completion and expiry, and payment failure events.
+
+`getWebhookDelivery` returns the immutable event payload, replay lineage, and complete attempt timeline. Attempts include start/completion timestamps, duration, status, a stable error category, safe request-header evidence, and a sanitized response excerpt capped at 4 KB. `listWebhookDeliveryAttempts` returns that timeline directly. `replayWebhookDelivery` requires an `idempotencyKey`, creates a new delivery linked to the source, and preserves the original event ID and payload. Confirm that your handler deduplicates by event ID before replaying.
+
+Failure categories are `dns`, `connection`, `tls`, `timeout`, `blocked_destination`, `http_4xx`, `http_5xx`, `redirect`, `response_too_large`, `signing_secret`, `endpoint_disabled`, and `internal`. Payclave does not follow redirects, and every 2xx response counts as success.
 
 Payclave returns the endpoint `signingSecret` once when the endpoint is created. Store it securely and use it to verify incoming webhook deliveries.
 
+Rotate a secret without interrupting deliveries:
+
+```ts
+const rotated = await payclave.rotateWebhookSecret(endpointId, {
+  idempotencyKey: "rotate_webhook_2026_08",
+})
+
+// Store rotated.signingSecret immediately; it is returned only once.
+await payclave.createTestWebhook({ endpointId })
+
+await payclave.endWebhookSecretOverlap(endpointId, {
+  idempotencyKey: "end_webhook_overlap_2026_08",
+})
+```
+
+The previous secret remains valid for at most 24 hours. During that overlap,
+Payclave signs each delivery with the new secret first and the previous secret
+second. A successful test event marks the current secret as tested; Payclave
+sends a reminder six hours before expiry only if no successful test has been
+recorded. Endpoint reads expose version timestamps, never hashes, ciphertext,
+or a previously returned secret.
+
 ## Webhook signatures
 
 Verify Payclave webhooks against the exact raw request body:
@@ -117,9 +300,11 @@ export async function POST(request: Request) {
 }
 ```
 
-`constructPayclaveWebhookEvent` throws `PayclaveError` when the signature, timestamp, or payload is invalid. Use `verifyPayclaveWebhookSignature` when you only need a boolean.
+`constructPayclaveWebhookEvent` throws `PayclaveError` when the signature, timestamp, or payload is invalid. A signature mismatch links to the [raw-body integration guide](https://www.payclave.com/developers/docs#webhooks). Use `verifyPayclaveWebhookSignature` when you only need a boolean.
+
+Webhook deliveries include `X-Payclave-Signature`, `X-Payclave-Timestamp`, `X-Payclave-Delivery`, and `X-Payclave-Event` headers. The normal signature format is `t=<unix_timestamp>,v1=<hex_hmac_sha256>`. During a rotation overlap it is exactly `t=<timestamp>,v1=<new signature>,v1=<old signature>`. The verifier checks every `v1` value in constant time, so it accepts the matching old or new endpoint secret during migration.
 
-Webhook deliveries include `X-Payclave-Signature`, `X-Payclave-Timestamp`, `X-Payclave-Delivery`, and `X-Payclave-Event` headers. The signature format is `t=<unix_timestamp>,v1=<hex_hmac_sha256>`.
+Any 2xx response acknowledges a delivery. After the first four failed attempts, Payclave retries after 1 minute, 5 minutes, 30 minutes, and 2 hours. A fifth failed attempt ends automatic retries.
 
 ## Errors