@wefunder/sdk 0.1.0-beta.1 → 0.1.0-beta.10

package/README.md

@@ -1,31 +1,29 @@
-# @wefunder/sdk (beta)
+# @wefunder/sdk
 
 [![CI](https://github.com/Wefunder/wefunder-node/actions/workflows/ci.yml/badge.svg)](https://github.com/Wefunder/wefunder-node/actions/workflows/ci.yml)
 
-Official TypeScript SDK for the [Wefunder API](https://docs.wefunder.com/api-reference).
+The official TypeScript SDK for the [Wefunder API](https://docs.wefunder.com/api-reference).
 
-> **Beta.** The package is `0.x` — breaking changes are possible while we
-> stabilize. Feedback welcome.
+The SDK is currently in beta. Releases may include breaking changes until the API reaches `1.0`.
+
+## Install
 
 ```bash
-npm install @wefunder/sdk
+npm install @wefunder/sdk@beta
 ```
 
-Node 18+ (uses the global `fetch`). ESM and CommonJS both supported.
+Node 20 or newer is required. Both ESM and CommonJS are supported.
+
+## Authentication
 
-### Scope & versioning
+Wefunder supports two OAuth grants:
 
-- **Surface:** this release covers the **stable + beta** public API (offerings,
-  investments, campaigns, syndicates, intents, attribution). Preview-only endpoints
-  (the partner SPV / sandbox-simulation surface) are intentionally **not** included yet.
-- **API version:** the SDK sends `Wefunder-Version: 2025-01-15` on every request,
-  forward-compatible with Wefunder's dated-version model. **The API does not resolve
-  this header yet**, so version pinning is not enforced server-side until that ships —
-  the header is correct in shape and will start taking effect transparently.
+- Use `client_credentials` for server-to-server access to public data.
+- Use `authorization_code` with PKCE when acting on behalf of a user.
 
-## Quickstart (server-to-server)
+### Server-to-server
 
-The fastest path: a `client_credentials` grant with a sandbox token, no user redirect.
+Create a client with your application's client ID and secret:
 
 ```ts
 import { Wefunder } from "@wefunder/sdk";
@@ -36,186 +34,264 @@ const wf = await Wefunder.fromClientCredentials({
   scopes: ["read:public"],
 });
 
-// A client_credentials token can only hold `read:public` — it acts as your app,
-// with no user. So it can browse public offerings, but NOT user-scoped data.
 const page = await wf.offerings.list();
-console.log(`${page.data?.length} offerings`);
 ```
 
-> **`wf.users.me()` won't work with `client_credentials`.** `/users/me` requires
-> `read:profile`, a user-context scope — calling it with a `client_credentials`
-> token throws `WefunderError` (`403 insufficient_scope`). To read user data, use
-> the `authorization_code` + PKCE flow below and request `read:profile`.
-
-## Authentication
+Client-credentials tokens represent the application, not a user. They cannot be used for user-scoped endpoints such as `wf.users.me()` or `wf.portfolio.get()`.
 
-The SDK supports both OAuth 2.0 grants the API offers.
+The SDK obtains a new token automatically when a client-credentials token expires.
 
-### `client_credentials` (server-side)
+### User authorization with PKCE
 
-`Wefunder.fromClientCredentials({ clientId, clientSecret, scopes })` — see above.
-These tokens are short-lived and have no refresh token, but the client keeps the
-grant inputs and **auto-re-mints** on expiry or a `401` — so a long-lived server can
-hold one `wf` and never hand-roll token recovery.
-
-### `authorization_code` + PKCE (acting on behalf of a user)
+Generate the authorization URL on your server. Store the state and PKCE verifier in the user's session before redirecting them:
 
 ```ts
-import { generatePkce, createAuthorizationUrl, exchangeCode, Wefunder } from "@wefunder/sdk";
+import { createAuthorizationUrl, generatePkce } from "@wefunder/sdk";
+import { randomBytes } from "node:crypto";
 
-// 1. Before redirecting, generate PKCE + a state token and stash them in the session.
 const pkce = generatePkce();
-const url = createAuthorizationUrl({
-  clientId, redirectUri, scopes: ["read:investments"], state, pkce,
+const state = randomBytes(32).toString("base64url");
+
+await saveOAuthAttempt({ state, codeVerifier: pkce.codeVerifier });
+
+const authorizationUrl = createAuthorizationUrl({
+  clientId,
+  redirectUri,
+  scopes: ["read:investments"],
+  state,
+  pkce,
 });
-// redirect the user to `url`
+```
+
+On the callback, validate the state and exchange the authorization code:
+
+```ts
+import { exchangeCode, Wefunder } from "@wefunder/sdk";
+
+const attempt = await consumeOAuthAttempt(state);
+if (!attempt) throw new Error("Invalid OAuth state");
 
-// 2. On the callback, exchange the code (+ verifier) for tokens.
 const tokens = await exchangeCode({
-  clientId, code, redirectUri, codeVerifier: pkce.codeVerifier,
+  clientId,
+  clientSecret, // optional for public clients
+  code,
+  redirectUri,
+  codeVerifier: attempt.codeVerifier,
 });
 
-// 3. Build a client. Pass clientId so it can auto-refresh on expiry.
-const wf = new Wefunder({ tokens, clientId, onTokenRefresh: (t) => saveToDb(t) });
+const wf = new Wefunder({
+  tokens,
+  clientId,
+  clientSecret,
+  store: {
+    save: (nextTokens) => saveTokens(nextTokens),
+  },
+});
 ```
 
-### Refresh tokens rotate — persist every refresh
+Keep access tokens, refresh tokens, OAuth state, and PKCE verifiers on the server. Encrypt persisted tokens at rest.
+
+### Refresh tokens
+
+Refresh tokens rotate. When the SDK refreshes an access token, it calls `store.save()` with the new token set before continuing the request. Persist the entire token set each time.
 
-Wefunder **rotates** refresh tokens: each refresh returns a *new* refresh token and
-invalidates the old one. The SDK refreshes automatically (proactively before expiry,
-and on a `401`), coalescing concurrent refreshes into one. You just have to persist
-the rotated token so it survives a restart:
+Load the saved tokens yourself when constructing a client after a process restart:
 
 ```ts
+const tokens = await loadTokens();
+
 const wf = new Wefunder({
   tokens,
   clientId,
-  store: {
-    load: () => db.loadTokens(),
-    save: (t) => db.saveTokens(t), // called on every rotation
-  },
+  clientSecret,
+  store: { save: saveTokens },
 });
 ```
 
-### Hosts (advanced)
+If several application instances can use the same OAuth connection, serialize refreshes for that connection. This prevents two instances from trying to rotate the same refresh token at once.
+
+## Calling the API
+
+Common resources are available through typed namespaces:
+
+```ts
+const offerings = await wf.offerings.list({ sort: "newest" });
+const investments = await wf.investments.list({ company_id: "co_example" });
+const portfolio = await wf.portfolio.get();
+```
+
+Namespaces: `users`, `offerings`, `investments`, `portfolio`, `campaigns`, `syndicates`, `intents`, `attribution`, and `webhookEndpoints`.
 
-OAuth uses two hosts, independently overridable:
+`wf.investments` is the Investment Delta API. `list()` without a cursor bootstraps; pass `updated_since` or the `meta.next_cursor` you saved from your last page to receive only records that changed since then. `next_cursor` is always present, even on the final page, so persist it after every sync.
 
-- **authorize host** — the browser consent redirect (`createAuthorizationUrl`). Defaults to `https://wefunder.com/oauth`.
-- **token host** — `/token` + refresh (`fromClientCredentials`, `exchangeCode`, refresh). Defaults to `https://wefunder.com/oauth` today; it will move to `https://api.wefunder.com/oauth` when Wefunder's edge gateway ships. Override via `tokenBaseUrl` (or set both at once with `oauthBaseUrl`).
+The methods available to a client depend on its OAuth scopes. Consult the [API reference](https://docs.wefunder.com/api-reference) for the scope required by each endpoint.
 
-The **API base** is `WefunderOptions.baseUrl` (default `https://api.wefunder.com/api/v2`). When Wefunder ships version-free URLs, the canonical base drops `/api/v2`; the current path stays as a back-compat alias, so no change is required on your side.
+The API base URL is `https://api.wefunder.com`. Paths are version-free; the SDK sends the API version in the `Wefunder-Version` request header.
 
 ## Pagination
 
-List endpoints auto-paginate. The cursor is opaque — you never construct it. List
-methods take the endpoint's documented query params, and they're preserved across pages.
+List namespaces provide three ways to work with paginated results:
 
 ```ts
-// Stream lazily (one page fetched at a time):
-for await (const inv of wf.investments.all()) {
-  console.log(inv.id);
-}
+// Fetch one page and inspect its cursor.
+const page = await wf.offerings.list({ sort: "newest" });
+console.log(page.data, page.meta?.next_cursor);
 
-// Query params are forwarded — e.g. sort the offerings browser (sort is preserved
-// on every page):
+// Fetch pages lazily.
 for await (const offering of wf.offerings.all({ sort: "most_raised" })) {
   console.log(offering.id);
 }
 
-// Or collect everything:
-const all = await wf.investments.collect();
-
-// Or drive pages yourself (gives you `meta`):
-const page = await wf.offerings.list({ sort: "newest" });
-console.log(page.data, page.meta?.next_cursor);
+// Fetch all results into an array.
+const investments = await wf.investments.collect();
 ```
 
-## Errors
+Cursors are opaque. Pass the value returned by the API without modifying it.
+
+## Errors and retries
 
-Failed requests throw `WefunderError` with the fields from the API's error envelope,
-including the `request_id` (read from the response body) — quote it in support tickets.
+API failures throw `WefunderError`:
 
 ```ts
 import { WefunderError } from "@wefunder/sdk";
 
 try {
-  await wf.syndicates.get(123);
-} catch (err) {
-  if (err instanceof WefunderError) {
-    console.error(err.status, err.type, err.message, err.requestId);
+  await wf.syndicates.get("syn_example");
+} catch (error) {
+  if (error instanceof WefunderError) {
+    console.error(error.status, error.type, error.message, error.requestId);
   }
 }
 ```
 
-Idempotent `GET`s are retried automatically on transient `5xx`/network errors and on
-`429` (honoring `X-RateLimit-Reset`). Writes are never auto-retried.
+The SDK retries idempotent `GET` requests after transient network errors, `5xx` responses, and rate limits. Write requests are not retried automatically.
 
 ## Webhooks
 
-Verify and parse webhook deliveries. Pass the **raw** request body (not a re-serialized
-object) and the headers:
+Webhooks deliver platform events (`investment.executed`, `offering.opened`, `investment.changed`, …) to an HTTPS endpoint you register. Every delivery is signed; the SDK verifies the signature, parses the envelope, and gives you a typed event.
+
+### 1. Register an endpoint
+
+Endpoints belong to your application and are managed through the live API (scope `write:webhooks`, org owner/admin/developer role). The signing secret is returned only on create and rotate, so store it immediately.
+
+```ts
+const endpoint = await wf.webhookEndpoints.create({
+  url: "https://yourapp.com/webhooks/wefunder", // public HTTPS; localhost and private IPs are rejected
+  events: ["offering.opened", "investment.executed"],
+  mode: "live", // "test" endpoints receive sandbox events
+});
+
+await saveSecret(endpoint.attributes!.secret!);
+```
+
+`wf.webhookEndpoints` also provides `list`, `get`, `update`, `remove`, `rotateSecret`, `reenable`, and `test`.
+
+### 2. Verify and handle deliveries
+
+Pass the raw request body, the request headers, and your secret to `constructEvent`. It throws `WebhookSignatureError` (with a `reason`) when a delivery is not authentic.
 
 ```ts
-import { constructEvent } from "@wefunder/sdk";
+import { constructEvent, dispatchWebhook, WebhookSignatureError } from "@wefunder/sdk";
 
-app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
+app.post("/webhooks/wefunder", express.raw({ type: "*/*" }), async (req, res) => {
   let event;
   try {
-    event = constructEvent(req.body.toString("utf8"), req.headers, process.env.WEBHOOK_SECRET!);
-  } catch {
-    return res.status(400).send("invalid signature");
+    event = constructEvent(req.body, req.headers, process.env.WEFUNDER_WEBHOOK_SECRET!);
+  } catch (err) {
+    if (err instanceof WebhookSignatureError) return res.status(400).send(err.reason);
+    throw err;
   }
-  // event.event, event.deliveryId, event.data
-  res.sendStatus(200);
+
+  res.sendStatus(200); // acknowledge first, then do the work
+
+  await dispatchWebhook(event, {
+    "investment.executed": async (e) => recordFunding(e.data.id, e.data.amounts.committed),
+    "offering.opened": async (e) => announce(e.data.company.name),
+    default: (e) => console.log("unhandled", e.event),
+  });
 });
 ```
 
-## Escape hatch: `wf.raw`
+`event` is a discriminated union, so narrowing on `event.event` types `event.data` for you. For fetch-style servers (Next.js route handlers, Hono, Cloudflare Workers), use `constructEventFromRequest(request, secret)` instead.
+
+Deliveries are at-least-once and unordered. Deduplicate on `event.id`, and where a payload carries `occurred_at`, keep the state from the latest one you have seen.
 
-Ergonomic namespaces cover the common GA resources. Every generated operation is also
-available, pre-bound, under `wf.raw`. Raw ops return the low-level `{ data, error,
-response }` result; wrap them in `wf.unwrap(...)` to get the same typed-error +
-envelope handling the namespaces use (a `WefunderError` with `request_id` on failure):
+### 3. Test your handler
+
+`wf.webhookEndpoints.test(endpoint.id)` sends a real, signed example event to your endpoint and reports the outcome inline. To unit-test your handler without the API, sign a fixture yourself:
 
 ```ts
-const members = await wf.unwrap(wf.raw.listSyndicateMembers({ path: { syndicate_id: 1 } }));
+import { signWebhook } from "@wefunder/sdk";
+
+const body = JSON.stringify({ id: "evt_1", event: "offering.opened", created_at: "…", mode: "test", data: {…} });
+const header = signWebhook({ payload: body, secret });
+// POST `body` to your handler with `Wefunder-Signature: ${header}`
+```
+
+### Secret rotation
+
+`wf.webhookEndpoints.rotateSecret(id)` returns a new secret; the old one keeps signing for 24 hours, and deliveries carry a `v1` for each. `constructEvent` accepts either, so you can roll the new secret out to your servers without dropping an event.
+
+### Signature scheme
+
+Each delivery carries `Wefunder-Signature: t=<unix seconds>,v1=<hex>` where `v1` is `HMAC-SHA256(secret, "<t>.<raw body>")`. Requests whose `t` is more than five minutes from now are rejected (`toleranceSeconds` adjusts this). `verifyWebhook` and `checkWebhookSignature` expose the check without parsing, and `constructEvent` still accepts the retired attribution-webhook headers (`X-Wefunder-Signature`/`X-Wefunder-Timestamp`).
 
-// Or handle the raw result yourself:
-const res = await wf.raw.listSyndicateMembers({ path: { syndicate_id: 1 } });
+## Generated operations
+
+Typed namespaces cover the most common resources. Every operation in the public OpenAPI specification is also available under `wf.raw`.
+
+```ts
+const members = await wf.unwrap(
+  wf.raw.listSyndicateMembers({
+    path: { syndicate_id: "syn_example" },
+  }),
+);
 ```
 
+Raw operations return `{ data, error, response }`. Passing the result to `wf.unwrap()` applies the same error handling used by the resource namespaces.
+
 ## Development
 
 ```bash
 npm install
-npm run generate   # regenerate src/generated from spec/openapi.yaml
 npm run typecheck
-npm test           # hermetic unit tests (no network)
-npm run test:e2e   # live sandbox E2E — needs WEFUNDER_CLIENT_ID/SECRET (or a .env); auto-skips otherwise
+npm run typecheck:examples
+npm test
 npm run build
 ```
 
-The live E2E hits `api.wefunder.com` with a sandbox app's `client_credentials`. Put
-the credentials in a gitignored `.env` (`WEFUNDER_CLIENT_ID=` / `WEFUNDER_CLIENT_SECRET=`).
+`npm run test:e2e` runs against the sandbox when `WEFUNDER_CLIENT_ID` and `WEFUNDER_CLIENT_SECRET` are set.
 
-The typed layer in `src/generated/` is produced by `@hey-api/openapi-ts` from
-`spec/openapi.yaml` and is never hand-edited. The hand-written shell in `src/` wraps it.
+Generated files in `src/generated/` come from `spec/openapi.yaml` and should not be edited by hand.
 
-### Syncing the spec (maintainers)
+### Conformance vectors
 
-`spec/openapi.yaml` is a vendored copy of the **public tier** (stable + beta) of the
-canonical Wefunder swagger. Preview/internal operations are excluded by design. To
-refresh it from a local wefunder checkout:
+`conformance/*.json` is the cross-language behavioural contract shared with the Python and Ruby
+SDKs (signatures, token rotation, pagination, retries, errors). `test/conformance.test.ts` runs
+every case; the vectors are frozen — fix the shell, not the vector. After deliberately changing
+one, run `npm run build:conformance` to refresh `conformance/manifest.json`. See
+[`conformance/README.md`](conformance/README.md).
+
+### Updating the API specification
+
+Run the sync command against a local checkout of the Wefunder application, then regenerate the client:
 
 ```bash
-WEFUNDER_REPO=/path/to/wefunder npm run sync-spec
+npm run sync-spec -- /path/to/wefunder
 npm run generate
-git add spec src/generated   # commit both together
+npm run typecheck
+npm test
+```
+
+Commit the specification and generated client together.
+
+### Releasing
+
+Releases are published by GitHub Actions. From a clean `main` branch:
+
+```bash
+npm version prerelease --preid beta
+git push --follow-tags
 ```
 
-`sync-spec` delegates filtering to the wefunder repo's own `build-filtered-spec.js`,
-so the public-tier definition can't drift between the two repos. CI's
-`generated code matches spec` job verifies `src/generated` matches the committed spec;
-it cannot reach the private canonical swagger, so run `sync-spec` before cutting a
-release. (`npm test` stays hermetic.)
+The release workflow runs the package checks and publishes prereleases to npm's `beta` tag.