@atribu/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to `@atribu/sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-05-15
+
+DX polish bundle. No breaking changes to v0.1.0 — every new feature is opt-in or additive.
+
+### Added
+
+- **Opt-in retry layer**: `new AtribuClient({...}).withRetry({ maxAttempts, backoff, baseDelayMs, jitter })`. Respects the typed retry hint — only retries `retry` / `retry_after` actions, never `do_not_retry` / `fix_and_retry` / `refresh_token`. Honors `Retry-After` exactly (no jitter); applies jittered exponential / fixed backoff otherwise.
+- **`isRetryableError(err)`** helper for consumers building their own retry logic.
+- **`@atribu/sdk/test` subpath** with MSW v2 handlers (`atribuMockHandlers()`) covering every OAuth-consumer endpoint, plus `eventFixtures` and `responseFixtures` for driving handler tests with realistic event shapes. Deep-merge overrides for any field.
+- **Compile-time type tests** via `vitest/expectTypeOf` — 12 narrowing assertions on the webhook event union, message content union, error hierarchy, retry-hint shape, and client surface. Fail-fast on accidental type-shape drift.
+- **OpenTelemetry recipe** in README — drop-in `tracedFetch` wrapper threading `traceparent`, surfacing `X-Request-Id` as a span attribute, recording HTTP status / errors. Works with any OTel-compatible tracer (Datadog APM, Sentry, native).
+
+### Changed
+
+- Resources now accept a `HttpClientLike` interface instead of the concrete `HttpClient` class so the retry wrapper stacks cleanly on top. Pure internal refactor, public API unchanged.
+- `msw` added as optional peer dependency (for `@atribu/sdk/test` users only).
+
+## [0.1.0] — 2026-05-15
+
+Initial pre-1.0 release. OAuth-consumer surface only — analytics endpoints land in a separate SDK once Atribu's add-on monetization path is built.
+
+### Added
+
+- `AtribuClient` with typed `messages.send`, `comments.reply`, `comments.privateReply`, `webhooks.subscriptions.{list,create,update,delete,rotateSecret,test}`, `webhooks.deliveries.replay`.
+- `@atribu/sdk/webhooks` — `verifyWebhook` via Web Crypto (Node + Edge runtimes), rotation grace, timestamp tolerance, constant-time HMAC compare.
+- `@atribu/sdk/oauth` — `buildAuthorizeUrl`, `exchangeCode`, `revokeToken`, `signIdTokenHint` (jose), `generateCodeVerifier`, `computeCodeChallenge` (PKCE RFC 7636).
+- `@atribu/sdk/admin` — `AtribuAdminClient` with `oauthApps.{create,update,suspend,rotateClientSecret,rotateJwtSecret}`.
+- `@atribu/sdk/next` — `withAtribuWebhook` HOF for Next.js App Router route handlers.
+- Typed error hierarchy: `AtribuError`, `AtribuApiError`, `AtribuOauthError`, `AtribuWebhookError`, `AtribuTransportError`, `AtribuConfigError`.
+- Retry hint surfaced on every `AtribuApiError` (`retry`, `retry_after`, `refresh_token`, `fix_and_retry`, `do_not_retry`). SDK does not auto-retry.
+- `Idempotency-Key` automatically sent on every mutating call.
+- OpenAPI-driven request/response types — zero drift from server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atribu
+
+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,431 @@
+# @atribu/sdk
+
+Official TypeScript SDK for the Atribu OAuth-consumer API. Send WhatsApp + Instagram messages on behalf of users who authorized your app, verify signed webhook deliveries, and run the consumer-side OAuth 2.0 flow without rolling your own JWT/PKCE crypto.
+
+Runs on Node 18+, Bun, Deno, Vercel Edge, and Cloudflare Workers via Web Crypto. No browser support — API keys don't belong in client-side JS.
+
+## Install
+
+```bash
+npm install @atribu/sdk
+# optional, only needed for the OAuth /oauth helpers:
+npm install jose
+```
+
+## Quickstart — send a message
+
+```ts
+import { AtribuClient } from "@atribu/sdk";
+
+const atribu = new AtribuClient({
+  apiKey: process.env.ATRIBU_API_KEY!,           // "atb_live_..."
+  // baseUrl: "http://localhost:3000",           // for local dev
+});
+
+const result = await atribu.messages.send({
+  connection_id: "11111111-1111-1111-1111-111111111111",
+  channel: "whatsapp",
+  to: "+15551234567",
+  content: { type: "text", text: "Hi! Thanks for reaching out." },
+});
+
+console.log(result.provider_message_id);
+```
+
+## Verifying inbound webhooks
+
+```ts
+// app/api/atribu-webhook/route.ts (Next.js App Router)
+import { withAtribuWebhook } from "@atribu/sdk/next";
+
+export const POST = withAtribuWebhook({
+  secret: process.env.ATRIBU_WEBHOOK_SECRET!,
+  previousSecret: process.env.ATRIBU_WEBHOOK_PREVIOUS_SECRET, // optional, during rotation
+  onEvent: async (event) => {
+    if (event.type === "message.received" && event.provider === "whatsapp") {
+      console.log("new WA message:", event.data.text);
+      // event.data is typed: { wa_message_id, from, to, contact_name, type, text, raw }
+    }
+  },
+});
+```
+
+Or roll your own handler:
+
+```ts
+import { verifyWebhook } from "@atribu/sdk/webhooks";
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const signature = req.headers.get("x-atribu-signature");
+  try {
+    const event = await verifyWebhook({
+      rawBody,
+      signature,
+      secret: process.env.ATRIBU_WEBHOOK_SECRET!,
+    });
+    // handle event ...
+    return new Response(null, { status: 200 });
+  } catch {
+    return new Response("invalid signature", { status: 401 });
+  }
+}
+```
+
+Atribu signs every delivery as `X-Atribu-Signature: t=<unix>,v1=<hex_hmac_sha256>` over `<t>.<rawBody>` (Stripe-style). The verifier:
+
+- enforces a timestamp tolerance (default 5 minutes) to defend against replay
+- constant-time compares the HMAC
+- accepts the `previousSecret` during rotation grace so you can dual-verify safely
+
+The unique `event.id` plus the `X-Atribu-Delivery-Id` header give you idempotency keys for safe redelivery.
+
+## Consumer-side OAuth flow
+
+If you're building an app that connects your end-users' WhatsApp/Instagram accounts via Atribu (Zernio-style), the `/oauth` subpath has every helper you need.
+
+```ts
+import {
+  signIdTokenHint,
+  buildAuthorizeUrl,
+  generateCodeVerifier,
+  computeCodeChallenge,
+  exchangeCode,
+  revokeToken,
+} from "@atribu/sdk/oauth";
+
+// 1. Redirect the user to Atribu's consent page
+const idTokenHint = await signIdTokenHint({
+  jwtSigningSecret: process.env.ATRIBU_APP_JWT_SECRET!,
+  subject: user.id,
+  email: user.email,
+  expiresIn: "5m",
+});
+
+const codeVerifier = generateCodeVerifier();
+const codeChallenge = await computeCodeChallenge(codeVerifier);
+
+const authorizeUrl = buildAuthorizeUrl({
+  clientId: "vitrina",
+  redirectUri: "https://vitrina.app/integrations/atribu/callback",
+  provider: "whatsapp",
+  scope: "whatsapp",
+  state: csrfToken,
+  idTokenHint,
+  codeChallenge,
+  codeChallengeMethod: "S256",
+});
+
+// 2. In your /callback handler:
+const { accessToken, connectionId, scope, profileId } = await exchangeCode({
+  clientId: "vitrina",
+  clientSecret: process.env.ATRIBU_APP_CLIENT_SECRET!,
+  code: callbackQuery.code,
+  redirectUri: "https://vitrina.app/integrations/atribu/callback",
+  codeVerifier,
+});
+
+// store accessToken (it's an Atribu API key) + connectionId per user
+
+// 3. To revoke later (e.g. user disconnects):
+await revokeToken({
+  clientId: "vitrina",
+  clientSecret: process.env.ATRIBU_APP_CLIENT_SECRET!,
+  token: accessToken,
+});
+```
+
+## Managing webhook subscriptions
+
+```ts
+// the OAuth flow creates a subscription automatically; manage it after:
+const subs = await atribu.webhooks.subscriptions.list();
+
+await atribu.webhooks.subscriptions.update(subs[0].id, {
+  url: "https://vitrina.app/api/atribu-webhook-v2",
+  events: ["message.received", "message.delivery"],
+  providers: ["whatsapp", "instagram"],
+});
+
+// rotate the HMAC secret — capture the new secret and deploy dual-verify BEFORE rotating
+const rotated = await atribu.webhooks.subscriptions.rotateSecret(subs[0].id, { grace_days: 14 });
+console.log("new webhook secret (shown once):", rotated.secret);
+
+// fire a synthetic event to test your handler
+await atribu.webhooks.subscriptions.test(subs[0].id);
+
+// re-deliver a dead webhook
+await atribu.webhooks.deliveries.replay(deadDeliveryId);
+```
+
+## IG comment replies
+
+```ts
+// public reply on the comment thread
+await atribu.comments.reply({
+  comment_id: "ig_comment_id",
+  connection_id: connectionId,
+  text: "Thanks for the message! DMing you details.",
+});
+
+// private DM to the user who left the comment
+await atribu.comments.privateReply({
+  comment_id: "ig_comment_id",
+  connection_id: connectionId,
+  text: "Here are the details you asked about ...",
+});
+```
+
+## Opt-in retry
+
+The SDK doesn't retry automatically (hiding retries amplifies load on a failing server and obscures backpressure). Opt in per-client when you want it:
+
+```ts
+import { AtribuClient } from "@atribu/sdk";
+
+const client = new AtribuClient({ apiKey: process.env.ATRIBU_API_KEY! })
+  .withRetry({
+    maxAttempts: 3,              // initial + 2 retries
+    backoff: "exponential",      // or "fixed" or "none"
+    baseDelayMs: 500,            // first retry waits ~500ms (+ jitter)
+    maxDelayMs: 30_000,
+    jitter: 0.3,                 // 0..1, multiplies delay by 1+random*jitter
+  });
+
+await client.messages.send({ ... });  // retries on 5xx / 408 / 429 / network glitches
+```
+
+What gets retried:
+
+| Condition | Behavior |
+|---|---|
+| 5xx, 408, `AtribuTransportError` (network) | Exponential backoff, jittered |
+| 429 / 503 with `Retry-After` | Honors the server's instruction exactly (no jitter) |
+| 401 (`refresh_token` hint) | **Not retried** — you need to refresh credentials, not retry |
+| 422 (`fix_and_retry` hint) | **Not retried** — your input is bad; retrying won't help |
+| 403 (`do_not_retry` hint) | **Not retried** — permission denied |
+
+`.withRetry()` returns a *new* client; the original is untouched. Chain it once at client construction and you're done.
+
+If you want to inspect retryability without using the wrapper:
+
+```ts
+import { isRetryableError } from "@atribu/sdk";
+
+try {
+  await client.messages.send({ ... });
+} catch (err) {
+  if (isRetryableError(err)) {
+    // queue this for retry on your side
+  } else {
+    throw err;
+  }
+}
+```
+
+## Testing with `@atribu/sdk/test`
+
+A drop-in MSW v2 setup so you can mock every Atribu endpoint with three lines:
+
+```ts
+// Install once: npm i -D msw
+import { afterAll, afterEach, beforeAll } from "vitest";
+import { setupServer } from "msw/node";
+import { atribuMockHandlers, fixtures } from "@atribu/sdk/test";
+
+const server = setupServer(...atribuMockHandlers());
+
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Every endpoint defaults to a realistic happy-path response. Override specific endpoints:
+
+```ts
+const server = setupServer(
+  ...atribuMockHandlers({
+    messages: {
+      send: {
+        status: 422,
+        body: { error: { code: "validation_error", message: "bad content", status: 422 } },
+      },
+    },
+  }),
+);
+```
+
+Or generate event payloads for your own webhook handler tests:
+
+```ts
+import { eventFixtures } from "@atribu/sdk/test";
+
+const event = eventFixtures.whatsappMessageReceived({
+  data: { text: "Custom test message", from: "+15551111111" },
+});
+
+// drive your handler with it
+await myWebhookHandler(event);
+```
+
+Available fixtures: `eventFixtures.{whatsappMessageReceived, whatsappMessageDelivery, instagramFbLoginMessage, instagramPostback, instagramIgLoginChange, instagramMessageDelivery}`. All deep-merge their overrides into a sensible default.
+
+## Error handling
+
+Every API error is an `AtribuApiError` with a typed `code` + machine-readable `retry` hint. **The SDK never retries automatically** — your queue / job system decides whether to act on the hint.
+
+```ts
+import { AtribuApiError } from "@atribu/sdk";
+
+try {
+  await atribu.messages.send({ ... });
+} catch (err) {
+  if (err instanceof AtribuApiError) {
+    switch (err.retry.action) {
+      case "retry":          // 5xx, transient
+        return queue.retry(job, { delay: 5_000 });
+      case "retry_after":    // 429 with Retry-After
+        return queue.retry(job, { delay: err.retry.retryAfterMs });
+      case "refresh_token":  // 401
+        return refreshOAuthAndRetry();
+      case "fix_and_retry":  // 422, 4xx caller error
+        return logger.error("bad payload", { err, requestId: err.requestId });
+      case "do_not_retry":   // 403, etc.
+        return logger.error("permanent failure", { err, requestId: err.requestId });
+    }
+  }
+  throw err;
+}
+```
+
+| Error class | When it's thrown |
+| --- | --- |
+| `AtribuApiError` | The server returned a non-2xx response for a `/api/v1/*` route. Has `code`, `status`, `requestId`, `retry`, `responseBody`. |
+| `AtribuOauthError` | The OAuth `/oauth/token` or `/oauth/revoke` endpoint returned an RFC-shaped error. Has `code`, `description`, `status`. |
+| `AtribuWebhookError` | A webhook signature failed verification. Has `code: "missing_signature" | "malformed_header" | "expired_timestamp" | "invalid_signature"`. |
+| `AtribuTransportError` | The HTTP request itself failed (network, abort, timeout). Has `cause`. |
+| `AtribuConfigError` | The SDK was configured incorrectly (missing API key, no `fetch` available, etc.). |
+
+Every successful request and every `AtribuApiError` surfaces the server's `X-Request-Id` header on `err.requestId` so you can grep server logs for "why".
+
+## Configuration
+
+```ts
+new AtribuClient({
+  apiKey: string,                              // required
+  baseUrl?: string,                            // default "https://www.atribu.app"
+  fetch?: typeof fetch,                        // default globalThis.fetch
+  timeoutMs?: number,                          // default 30000
+  userAgent?: string,                          // appended after the SDK UA
+  defaultIdempotencyKeyGenerator?: () => string,
+});
+```
+
+- **Custom `fetch`**: useful for instrumentation (Datadog APM, OTel), for testing (msw), or for runtimes where `globalThis.fetch` isn't the default.
+- **Timeout**: aborts the request via `AbortController` after the budget. Surface as `AtribuTransportError` with `name: "AbortError"` on the cause.
+- **Idempotency keys**: every mutating call automatically sends `Idempotency-Key: <uuid>`. Override per-call via `{ idempotencyKey }` or globally with `defaultIdempotencyKeyGenerator`.
+- **User-Agent**: format `@atribu/sdk/<version> (<runtime>)`. Server uses it for per-version analytics.
+
+## OpenTelemetry tracing
+
+The custom-`fetch` hook is enough — wrap your tracer around it and every SDK call becomes a child span. No SDK changes needed:
+
+```ts
+import { trace, SpanStatusCode, context, propagation } from "@opentelemetry/api";
+import { AtribuClient } from "@atribu/sdk";
+
+const tracer = trace.getTracer("my-app");
+
+const tracedFetch: typeof fetch = async (input, init) => {
+  const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+  const method = init?.method ?? "GET";
+
+  return tracer.startActiveSpan(`atribu.${method.toLowerCase()} ${new URL(url).pathname}`, async (span) => {
+    span.setAttributes({
+      "http.method": method,
+      "http.url": url,
+      "peer.service": "atribu-api",
+    });
+
+    // Inject W3C traceparent headers so server-side spans link up.
+    const headers = new Headers(init?.headers);
+    propagation.inject(context.active(), headers, {
+      set: (carrier, key, value) => carrier.set(key, value),
+    });
+
+    try {
+      const res = await fetch(input, { ...init, headers });
+      span.setAttribute("http.status_code", res.status);
+      const requestId = res.headers.get("x-request-id");
+      if (requestId) span.setAttribute("atribu.request_id", requestId);
+      if (res.status >= 400) {
+        span.setStatus({ code: SpanStatusCode.ERROR, message: `HTTP ${res.status}` });
+      }
+      return res;
+    } catch (err) {
+      span.recordException(err as Error);
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+};
+
+const atribu = new AtribuClient({
+  apiKey: process.env.ATRIBU_API_KEY!,
+  fetch: tracedFetch,
+});
+```
+
+Atribu's `X-Request-Id` response header lands as an attribute on every span — same key the server logs use, so you can pivot from a span to the server log with a single grep. Works the same with Datadog APM (`@datadog/dd-trace`), Sentry tracing, or any other fetch-instrumentation pattern.
+
+## Admin client (Atribu staff)
+
+If you're staff managing consumer apps, the `/admin` subpath wraps the `/api/v1/admin/oauth-apps/*` surface. Requires the `ATRIBU_ADMIN_SECRET`.
+
+```ts
+import { AtribuAdminClient } from "@atribu/sdk/admin";
+
+const admin = new AtribuAdminClient({
+  adminSecret: process.env.ATRIBU_ADMIN_SECRET!,
+});
+
+const app = await admin.oauthApps.create({
+  client_id: "vitrina",
+  name: "Vitrina",
+  redirect_uris: ["https://vitrina.app/integrations/atribu/callback"],
+  allowed_scopes: ["whatsapp", "instagram"],
+  created_by: "your-user-uuid",
+});
+
+// secrets are shown ONCE — store them safely
+console.log(app.client_secret, app.jwt_signing_secret);
+
+await admin.oauthApps.rotateClientSecret(app.id, { grace_days: 14 });
+await admin.oauthApps.suspend(app.id);  // kill-switch — revokes every api_key minted by this app
+```
+
+## Runtime support
+
+| Runtime | Supported | Notes |
+| --- | --- | --- |
+| Node 18+ | ✅ | Uses `globalThis.fetch` + Web Crypto |
+| Node 16 | ❌ | No native fetch; install `undici` and inject |
+| Bun | ✅ | |
+| Deno | ✅ | Import via `npm:@atribu/sdk` |
+| Vercel Edge | ✅ | |
+| Cloudflare Workers | ✅ | |
+| Browser | ❌ by design | API keys belong on a server |
+
+## Versioning
+
+SDK versions follow semver. Pre-1.0 (`0.x`) means the surface may still evolve based on real consumer feedback. Once Vitrina has shipped and the surface is stable, we'll bump to `1.0.0`.
+
+## Repository
+
+Source: [github.com/atribu/atribu/tree/main/packages/sdk](https://github.com/atribu/atribu/tree/main/packages/sdk)
+
+## License
+
+MIT