@papierapi/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Papier API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,450 @@
+# @papierapi/sdk
+
+The official TypeScript SDK for the Papier API. It provides a typed,
+runtime-validated ESM client for preparing, approving, paying for, dispatching,
+and tracking physical letters and faxes.
+
+The SDK is designed for trusted server-side applications. It validates request
+inputs before sending them, validates every API response against the published
+contract, and keeps real dispatch behind an explicit human approval.
+
+## Features
+
+- Typed letter and fax workflows
+- PDF uploads up to 20 MiB
+- Structured letter content without generating a PDF yourself
+- Human approval links before payment or dispatch
+- Direct-payment and wallet-backed dispatch flows
+- Idempotency keys for retry-safe payment and dispatch creation
+- Dispatch status, event, summary, and proof retrieval
+- Runtime response validation
+- Typed API, transport, and contract errors
+- Machine-readable operation metadata
+- Injectable access-token provider and Fetch implementation
+
+## Requirements
+
+- Node.js `>=20 <26`
+- An ESM application
+- A Papier API OAuth access token or API key
+- A configured sender profile for letter or fax drafts
+
+The package ships ESM JavaScript and TypeScript declarations. CommonJS
+`require()` is not supported.
+
+Create API credentials and sender profiles in the
+[Papier API developer area](https://app.papierapi.de/developers).
+
+## Installation
+
+```bash
+npm install @papierapi/sdk
+```
+
+Equivalent package-manager commands:
+
+```bash
+pnpm add @papierapi/sdk
+yarn add @papierapi/sdk
+```
+
+## Client setup
+
+```ts
+import { PapierApiClient } from "@papierapi/sdk";
+
+const api = new PapierApiClient({
+  baseUrl: "https://api.papierapi.de",
+  accessToken: process.env.PAPIERAPI_TOKEN!,
+});
+```
+
+Recommended environment variables:
+
+```dotenv
+PAPIERAPI_TOKEN=pap_...
+PAPIERAPI_SENDER_PROFILE_ID=snd_...
+```
+
+Keep credentials in a server-side secret manager. Do not bundle a Papier API
+token into browser JavaScript, mobile applications, source control, logs, or
+prompts.
+
+### Rotating or short-lived tokens
+
+`accessToken` may be a string or a synchronous or asynchronous provider. The
+provider is called immediately before each request.
+
+```ts
+const api = new PapierApiClient({
+  baseUrl: "https://api.papierapi.de",
+  accessToken: async () => secretManager.read("PAPIERAPI_TOKEN"),
+});
+```
+
+### Client options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | required | Absolute API origin. HTTPS is required except for localhost. Do not include `/v1`, a path, query, or fragment. |
+| `accessToken` | `string \| (() => string \| Promise<string>)` | required | OAuth access token or API key sent as a Bearer token. |
+| `fetcher` | Fetch-compatible function | `globalThis.fetch` | Custom transport for tests, tracing, proxies, or platform integration. |
+| `timeoutMs` | `number` | `30000` | Per-request timeout. Valid range: 1 to 120,000 ms. |
+| `maxResponseBytes` | `number` | `2097152` | Maximum accepted response body. Valid range: 256 bytes to 10 MiB. |
+
+## Workflow
+
+A real letter or fax is never sent by a draft or review call. The normal flow
+is:
+
+1. Upload a PDF or provide structured letter content.
+2. Create a draft.
+3. Quote the immutable draft.
+4. Create a human approval request.
+5. Let a person review the document, recipient, options, and final price.
+6. After approval, create a direct-payment session or a wallet-backed dispatch.
+7. Read the server-confirmed payment and dispatch status.
+
+Changing the document, recipient, options, or price requires a new approval.
+
+## Prepare a PDF letter for review
+
+`prepareLetterForReview()` creates a draft, quotes it, and creates an approval
+link. It does not pay for or send the letter.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { PapierApiClient } from "@papierapi/sdk";
+
+const api = new PapierApiClient({
+  baseUrl: "https://api.papierapi.de",
+  accessToken: process.env.PAPIERAPI_TOKEN!,
+});
+
+const pdf = await readFile("./contract.pdf");
+const upload = await api.uploadDocument(pdf);
+
+const review = await api.prepareLetterForReview({
+  sender_profile_id: process.env.PAPIERAPI_SENDER_PROFILE_ID!,
+  recipient: {
+    type: "street",
+    company: "Example Property Management GmbH",
+    name: "Contracts Department",
+    street: "Invalidenstrasse",
+    house_number: "1",
+    postal_code: "10115",
+    city: "Berlin",
+    country: "DE",
+  },
+  source: {
+    mode: "raw_pdf",
+    document_id: upload.data.document.id,
+  },
+  options: {
+    print: "grayscale",
+    duplex: true,
+    service: "standard",
+  },
+  metadata: {
+    external_reference: "contract-2026-0042",
+  },
+});
+
+console.log({
+  approvalRequestId: review.approval.id,
+  draftId: review.draft.id,
+  pages: review.draft.page_count,
+  totalCents: review.quote.total_cents,
+  approvalUrl: review.approval.approval_url,
+});
+```
+
+Open `approvalUrl` in a user-controlled browser. Preparing a review package is
+not evidence that the document was paid for, submitted to a provider, or sent.
+
+### Supported PDF input types
+
+`uploadDocument()` accepts:
+
+- `Blob`
+- `ArrayBuffer`
+- `Uint8Array`, including Node.js `Buffer`
+
+The local size limit is 1 byte through 20 MiB. The API performs additional PDF
+and layout validation.
+
+## Prepare a structured letter
+
+Use structured content when Papier API should render the document. The same
+draft, quote, and approval model applies.
+
+```ts
+const review = await api.prepareLetterForReview({
+  sender_profile_id: process.env.PAPIERAPI_SENDER_PROFILE_ID!,
+  recipient: {
+    type: "street",
+    name: "Max Mustermann",
+    street: "Beispielweg",
+    house_number: "4",
+    postal_code: "10115",
+    city: "Berlin",
+    country: "DE",
+  },
+  source: {
+    mode: "structured",
+    content: {
+      locale: "en-DE",
+      date: "2026-07-20",
+      subject: "Contract notice",
+      salutation: "Dear Mr Mustermann,",
+      blocks: [
+        {
+          type: "paragraph",
+          text: "This letter confirms the requested contractual notice.",
+        },
+        {
+          type: "list",
+          ordered: false,
+          items: ["Reference: 2026-0042", "Effective date: 31 July 2026"],
+        },
+      ],
+      closing: "Kind regards",
+      signatory: "Example Operations Team",
+    },
+  },
+  options: {
+    print: "grayscale",
+    duplex: false,
+    service: "registered_insertion",
+  },
+});
+
+console.log(review.approval.approval_url);
+```
+
+Structured blocks support paragraphs, headings, ordered or unordered lists,
+tables, spacers, closings, and signature placeholders. TypeScript exposes the
+accepted shapes through `CreateLetterDraftInput` and related exported types.
+
+## Prepare a fax for review
+
+Fax drafts use an uploaded PDF and an E.164 recipient number.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+const upload = await api.uploadDocument(await readFile("./signed-contract.pdf"));
+
+const review = await api.prepareFaxForReview({
+  sender_profile_id: process.env.PAPIERAPI_SENDER_PROFILE_ID!,
+  recipient: {
+    fax_number_e164: "+493012345678",
+    company: "Example Recipient GmbH",
+    name: "Contracts Department",
+    recipient_reference: "contract-2026-0042",
+  },
+  document_id: upload.data.document.id,
+  cover: {
+    enabled: true,
+    subject: "Signed contract",
+    note: "Please route this document to the contracts team.",
+  },
+  options: {
+    max_attempts: 2,
+    purpose: "contractual",
+  },
+});
+
+console.log(review.approval.approval_url);
+```
+
+Fax availability depends on the active Papier API environment and sender
+profile. A prepared fax is not proof of transmission.
+
+## Responses
+
+Individual client methods return a validated API envelope:
+
+```ts
+const response = await api.getDispatch("dsp_...");
+
+console.log(response.request_id);
+console.log(response.data.status);
+console.log(response.next_actions);
+```
+
+The concrete `data` type is inferred for every method. Responses that do not
+match the published schema are rejected with `PapierApiContractError` instead
+of being returned as untrusted data.
+
+## Client API
+
+### Documents, drafts, quotes, and approvals
+
+| Method | Purpose |
+| --- | --- |
+| `uploadDocument(document)` | Upload a PDF and return its document ID. |
+| `createLetterDraft(input)` | Create a letter draft from structured content or an uploaded PDF. |
+| `createFaxDraft(input)` | Create a fax draft from an uploaded PDF. |
+| `getDraft(draftId)` | Read a draft and its current verification state. |
+| `quoteDraft(draftId)` | Calculate a time-limited quote for a draft. |
+| `requestApproval(draftId, input)` | Create a human approval request and approval URL. |
+| `prepareLetterForReview(input, expiresInSeconds?)` | Create, quote, and request approval for a letter. Default approval lifetime: 3,600 seconds. |
+| `prepareFaxForReview(input, expiresInSeconds?)` | Create, quote, and request approval for a fax. Default approval lifetime: 3,600 seconds. |
+
+### Payment, dispatch, and status
+
+| Method | Purpose |
+| --- | --- |
+| `createDirectPaymentSession(draftId, input, idempotencyKey)` | Create user-controlled Checkout after approval. Opening Checkout does not dispatch. |
+| `getDirectPayment(directPaymentId)` | Read server-confirmed payment and resulting dispatch state. |
+| `createDispatch(draftId, input, idempotencyKey)` | Create a wallet-backed dispatch after approval. |
+| `listDispatches(limit?)` | List up to 100 dispatches. Default: 25. |
+| `getDispatch(dispatchId)` | Read the canonical dispatch state. |
+| `getDispatchSummary(dispatchId)` | Read a redacted channel-specific summary. |
+| `getDispatchEvents(dispatchId)` | Read persisted dispatch events. |
+| `getDispatchProof(dispatchId)` | Read the proof bundle and event-chain verification result. |
+| `cancelDispatch(dispatchId)` | Request cancellation of a dispatch. |
+| `getWallet()` | Read the current wallet balance. |
+
+The SDK does not automatically approve, pay for, or dispatch a draft.
+
+## Idempotency and retries
+
+The SDK does not automatically retry requests.
+
+`createDispatch()` and `createDirectPaymentSession()` require an idempotency
+key. Reuse a key only when retrying the identical logical operation.
+
+```ts
+async function createCheckout(draftId: string, quoteId: string, approvalId: string) {
+  const idempotencyKey = `checkout:${draftId}:${approvalId}`;
+
+  return api.createDirectPaymentSession(
+    draftId,
+    {
+      quote_id: quoteId,
+      approval_id: approvalId,
+    },
+    idempotencyKey,
+  );
+}
+```
+
+Idempotency keys must contain 8 to 200 letters, digits, dots, underscores,
+colons, or dashes. Consult `papierApiOperations[name].safeToRetry` before adding
+custom retry behavior around another operation.
+
+## Error handling
+
+```ts
+import {
+  PapierApiContractError,
+  PapierApiError,
+  PapierApiTransportError,
+} from "@papierapi/sdk";
+
+try {
+  const dispatch = await api.getDispatch("dsp_...");
+  console.log(dispatch.data.status);
+} catch (error) {
+  if (error instanceof PapierApiError) {
+    console.error({
+      status: error.status,
+      code: error.code,
+      requestId: error.requestId,
+      retryable: error.retryable,
+      fieldPath: error.fieldPath,
+      suggestedAction: error.suggestedAction,
+    });
+  } else if (error instanceof PapierApiTransportError) {
+    console.error({ reason: error.reason, retryable: error.retryable });
+  } else if (error instanceof PapierApiContractError) {
+    console.error({ operationId: error.operationId, status: error.status });
+  } else {
+    throw error;
+  }
+}
+```
+
+Error categories:
+
+| Error | Meaning |
+| --- | --- |
+| `PapierApiError` | The API returned a valid structured error response. |
+| `PapierApiTransportError` | The request timed out or the network was unavailable. |
+| `PapierApiContractError` | A response was malformed, too large, or incompatible with the SDK contract. |
+| `TypeError` | Client configuration, token, timeout, response limit, or PDF bounds are invalid. |
+| `ZodError` | A method input, identifier, query parameter, or idempotency key violates the published schema. |
+
+Use `requestId` when contacting support about an API response.
+
+## Operation registry
+
+The canonical machine-readable operation registry is exported from the
+side-effect-free `@papierapi/sdk/operations` entry point.
+
+```ts
+import {
+  papierApiOperations,
+  type PapierApiOperationName,
+  type PapierApiOperationResponse,
+} from "@papierapi/sdk/operations";
+
+const operationName = "getDispatch" satisfies PapierApiOperationName;
+const operation = papierApiOperations[operationName];
+
+console.log({
+  method: operation.method,
+  path: operation.path,
+  safeToRetry: operation.safeToRetry,
+  requiresIdempotencyKey: operation.requiresIdempotencyKey,
+});
+
+type GetDispatchResponse = PapierApiOperationResponse<"getDispatch">;
+```
+
+Each registry entry includes the HTTP method, path, request kind, path and query
+schemas, response schema, retry classification, and idempotency requirement.
+
+## Custom Fetch implementation
+
+Inject `fetcher` to integrate tracing, testing, a proxy, or another compatible
+runtime. It must implement the standard Fetch signature and return a standard
+`Response`.
+
+```ts
+const api = new PapierApiClient({
+  baseUrl: "http://127.0.0.1:8787",
+  accessToken: "pap_test_token",
+  fetcher: async (input, init) => {
+    telemetry.recordRequest(input, init);
+    return fetch(input, init);
+  },
+  timeoutMs: 10_000,
+});
+```
+
+Plain HTTP is accepted only for `localhost` and `127.0.0.1`. Production origins
+must use HTTPS.
+
+## Security and runtime behavior
+
+- Bearer tokens are resolved immediately before every request.
+- Request inputs and identifiers are validated before network access.
+- API responses are size-bounded and schema-validated before being returned.
+- Requests time out through `AbortController`.
+- PDF uploads are copied into a request `Blob` where required.
+- The SDK does not persist credentials, documents, responses, or approval data.
+- The SDK does not perform hidden retries or background dispatches.
+
+## API contract and support
+
+- [OpenAPI 3.1 contract](https://api.papierapi.de/openapi.json)
+- [Developer area](https://app.papierapi.de/developers)
+- [Product documentation](https://papierapi.de/entwickler)
+- Technical support: [support@papierapi.de](mailto:support@papierapi.de)
+
+## License
+
+MIT. See [LICENSE](LICENSE).