@workwae/sdk 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,234 @@
-# Temporary Holding Version
+# @workwae/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript client for the [workwae](https://workwae.com) API: one REST API for Gmail,
+Microsoft 365 and IMAP mailboxes, Google, Microsoft and CalDAV calendars, and contacts. Every
+method, input, answer and error is typed from the same contract the API is built on.
+
+- Typed methods for every `/v1` operation, with dates as `Date`
+- Cursor helpers for every listing and the change feed
+- Typed errors keyed by stable reasons, with the request id
+- Automatic retries of 429 and 503 answers, honoring `Retry-After`
+- Idempotency keys on every POST
+- Webhook signature verification (Standard Webhooks) and typed event parsing
+
+The full guides and API reference are in the board's docs, at `/docs` (`/docs/api` for every
+operation, `/docs/changelog` for what changed).
+
+## Install
+
+```sh
+bun add @workwae/sdk
+# or
+npm install @workwae/sdk
+# or
+pnpm add @workwae/sdk
+```
+
+The package is ESM only and runs on Node.js 20 or later, Bun, Deno, Cloudflare Workers and
+browsers (it needs `fetch` and Web Crypto, nothing else). Its runtime dependencies are `zod` and
+`@orpc/*`.
+
+## Create a client
+
+```ts
+import { createClient } from "@workwae/sdk";
+
+const workwae = createClient({ apiKey: process.env.WORKWAE_API_KEY });
+
+const { items: accounts, nextCursor } = await workwae.accounts.list({ limit: 50 });
+```
+
+| Option    | Meaning                                                                                       |
+| --------- | --------------------------------------------------------------------------------------------- |
+| `baseUrl` | Defaults to `https://api.workwae.com`. Set it only to route through your own proxy or gateway. |
+| `apiKey`  | An API key (`wk_...`), an account token (`wat_...`), or a function returning one per request. |
+| `headers` | Extra headers sent with every request.                                                        |
+| `fetch`   | Replaces the global `fetch` (a proxy agent, instrumentation, tests).                          |
+| `retry`   | `{ maxRetries, maxDelayMs, wait }`, see [Retries](#retries).                                  |
+
+Methods are named after the operation, grouped by resource: `workwae.accounts.get`,
+`workwae.outbox.create`, `workwae.calendarEvents.list`, `workwae.webhooks.replay`. Each takes one
+object holding the path, query and body fields together:
+
+```ts
+const message = await workwae.messages.get({ accountId, messageId });
+
+const queued = await workwae.outbox.create({
+  accountId,
+  to: [{ name: "Ada Lovelace", address: "ada@example.com" }],
+  subject: "Hello",
+  text: "Sent with workwae.",
+});
+```
+
+`DELETE` operations that take options keep the path and the query apart:
+
+```ts
+await workwae.accounts.delete({ params: { accountId }, query: { purge: true } });
+```
+
+A second argument carries per-call options: `signal` aborts the call (and any retry wait), and
+`context.idempotencyKey` sets the idempotency key.
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 10_000);
+await workwae.accounts.list({}, { signal: controller.signal });
+```
+
+## Authentication
+
+API keys are created on the board under **API keys**, with the scopes the integration needs
+(`read`, `write`, `send`, `admin`). They reach every account of the tenant, so keep them on your
+server.
+
+To let a browser or mobile app read one account directly, mint a short-lived account token on
+your server and hand it over; it is limited to that one account:
+
+```ts
+// Server
+const { token, expiresAt } = await workwae.accounts.mintToken({ accountId, ttlSeconds: 900 });
+
+// Browser: fetch a fresh token from your backend whenever the client needs one.
+const client = createClient({
+  apiKey: () => fetch("/api/workwae-token").then((response) => response.text()),
+});
+```
+
+## Pagination
+
+Listings answer `{ items, nextCursor }`; pass `nextCursor` back as `cursor` until it is `null`.
+The helpers take the method itself, so filters and item types stay typed:
+
+```ts
+import { changes, pages, paginate } from "@workwae/sdk";
+
+// Every item, to the last page.
+for await (const message of paginate(workwae.messages.list, { accountId, unread: true })) {
+  console.log(message.subject);
+}
+
+// Page by page.
+for await (const page of pages(workwae.accounts.list, { limit: 200 })) {
+  console.log(page.items.length, page.nextCursor);
+}
+
+// The change feed, until caught up. Persist feed.cursor after processing and resume from it:
+// a page is only passed once its last event was consumed (at-least-once delivery).
+const feed = changes(workwae.changes.list, { cursor: await loadCursor() });
+for await (const event of feed) await handle(event);
+await saveCursor(feed.cursor);
+```
+
+## Errors
+
+An API refusal is thrown as an `ORPCError` whose `code` is the error's stable reason
+(`account_not_found`, `invalid_input`, `plan_limit_sends`, ...), `status` its HTTP status,
+`message` a human-readable text, `data` the reason's details when it has any, and `requestId`
+the answer's `X-Request-Id` (quote it to support).
+
+```ts
+import { isApiError, isDefinedError, safe } from "@workwae/sdk";
+
+// safe() resolves to [error, data]; isDefinedError() narrows to the reasons the operation declares.
+const [error, account] = await safe(workwae.accounts.get({ accountId }));
+if (isDefinedError(error)) {
+  if (error.code === "account_not_found") {
+    // ...
+  }
+} else if (error) {
+  throw error;
+}
+
+// isApiError(error, reason) checks for one reason anywhere and narrows `data` to it.
+try {
+  await workwae.outbox.create({ accountId, to: [], text: "hi" });
+} catch (error) {
+  if (isApiError(error, "invalid_input")) console.log(error.data.issues);
+  else if (isApiError(error)) console.error(error.code, error.status, error.requestId);
+  else throw error;
+}
+```
+
+`ErrorReason` is the union of every reason. Errors that are not API answers (network failures,
+an aborted signal) are thrown as they are.
+
+## Retries
+
+429 (`rate_limited`, `too_many_requests`) and 503 (`overloaded`) answers are refused before the
+API acts, so the client retries them: twice by default, waiting for `Retry-After`, or backing off
+exponentially with jitter when there is none. A `Retry-After` longer than `maxDelayMs` is not
+waited for: the error is thrown.
+
+```ts
+const workwae = createClient({
+  apiKey,
+  retry: { maxRetries: 4, maxDelayMs: 30_000 },
+});
+```
+
+Rate-limited answers also carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`
+headers; read them through a custom `fetch` if you want to pace yourself.
+
+## Idempotency keys
+
+Every POST is sent with an `Idempotency-Key`, generated per call and reused across the client's
+own retries, so a retried send never goes out twice. To make a call safe to repeat across
+process restarts (a job queue retrying a send, say), pass a key of your own derived from your
+data:
+
+```ts
+await workwae.outbox.create(
+  { accountId, to: [{ address: "ada@example.com" }], subject: "Invoice 1042", text: "..." },
+  { context: { idempotencyKey: "invoice-1042" } },
+);
+```
+
+The API keeps the first answer for 24 hours per tenant and key and replays it for a repeat with
+the same body. The same key with a different body is refused with `idempotency_key_reused`; a
+repeat while the first call still runs with `idempotency_key_in_progress`.
+
+## Webhooks
+
+workwae signs deliveries with [Standard Webhooks](https://www.standardwebhooks.com/).
+`parseWebhook` verifies a delivery and returns its event, typed by `type`, with dates as `Date`.
+Pass the raw body exactly as received:
+
+```ts
+import { parseWebhook, WebhookVerificationError } from "@workwae/sdk";
+
+export async function POST(request: Request) {
+  const body = await request.text();
+  try {
+    const event = await parseWebhook(process.env.WORKWAE_WEBHOOK_SECRET!, request.headers, body);
+    if (event.known && event.type === "send.failed") {
+      console.log(event.data.outboxId, event.data.error.code);
+    }
+    // event.known is false for an event type added after this SDK version.
+    return new Response(null, { status: 204 });
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
+    throw error;
+  }
+}
+```
+
+`verifyWebhook(secret, headers, body)` only checks the signature and answers a boolean;
+`checkWebhookSignature` answers why it failed (`missing_headers`, `timestamp`, `signature`).
+Both accept a `toleranceSeconds` option (default `WEBHOOK_TOLERANCE_SECONDS`, 300).
+
+## Types
+
+Every model of the API is exported as a type, under the name the OpenAPI document gives it:
+
+```ts
+import type { Account, CalendarEvent, Event, EventType, Message, OutboxEntry } from "@workwae/sdk";
+```
+
+`EVENT_TYPES` lists every event type at runtime (for webhook endpoint filters), and the
+`MAX_TEMPLATE_*` constants are the template field limits.
+
+## Versioning
+
+The SDK follows semver from 0.1.0; while it is 0.x, a minor version may carry breaking changes,
+always listed in the changelog. Releases are tagged `sdk-v<version>` in the repository.

package/client.d.ts

@@ -0,0 +1,36 @@
+import type { ContractRouterClient } from "@orpc/contract";
+import { type V1Contract } from "./contract/public.js";
+/** Per call, as `{ context }`: `workwae.send.create(input, { context: { idempotencyKey } })`. */
+export interface CallContext {
+    /** The POST's Idempotency-Key. Without one, each POST call sends a key of its own, the same on
+     * every automatic retry. Pass one to make retries of your own (a later process, a timeout)
+     * answer what the first attempt did. */
+    idempotencyKey?: string;
+}
+/** Every /v1 procedure, typed from the contract: `workwae.accounts.get({ accountId })`. */
+export type WorkwaeClient = ContractRouterClient<V1Contract, CallContext>;
+export interface RetryOptions {
+    /** Further attempts after a 429 or 503. Default 2. */
+    maxRetries?: number;
+    /** Longest single wait. A Retry-After beyond it is not waited for: the error is thrown. Default
+     * 60 000 ms. */
+    maxDelayMs?: number;
+    /** How to wait between attempts; it should reject when `signal` aborts. Default: a timer. */
+    wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export interface ClientOptions {
+    /** The API origin; the /v1 paths are appended to it, so a path prefix is kept. Defaults to the
+     * hosted API; set it only to go through a proxy or gateway of your own. */
+    baseUrl?: string;
+    /** An API key (`wk_...`) or an account token (`wat_...`), or a function returning one per
+     * request, for tokens that are refreshed. */
+    apiKey?: string | (() => string | Promise<string>);
+    /** Extra headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Replaces the global fetch (a proxy agent, instrumentation, tests). Only this call shape is
+     * used, so a plain function works where a runtime's `typeof fetch` carries extra members. */
+    fetch?: (request: Request, init?: RequestInit) => Promise<Response>;
+    retry?: RetryOptions;
+}
+/** A typed client for the workwae /v1 API. */
+export declare function createClient(options: ClientOptions): WorkwaeClient;