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

package/README.md

@@ -120,7 +120,9 @@ 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`.
+Namespaces: `users`, `offerings`, `investments`, `portfolio`, `campaigns`, `syndicates`, `intents`, `attribution`, `installations`, and `webhookEndpoints`.
+
+`wf.offerings.stats(id)` returns an offering's aggregate investment stats. `wf.installations` lets your app act as a company or syndicate: `eligibleTargets()`, `create()`, `mintToken()`, `list()`, `get()`, `revoke()`, and `installOrMintToken()`, which handles the API's 409 `already_installed` answer by minting a token for the existing install with the same scopes.
 
 `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.
 
@@ -191,25 +193,39 @@ await saveSecret(endpoint.attributes!.secret!);
 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, dispatchWebhook, WebhookSignatureError } from "@wefunder/sdk";
-
-app.post("/webhooks/wefunder", express.raw({ type: "*/*" }), async (req, res) => {
-  let event;
-  try {
-    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;
-  }
-
-  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),
-  });
-});
+import {
+  constructEvent,
+  dispatchWebhook,
+  WebhookSignatureError,
+} from "@wefunder/sdk";
+
+app.post(
+  "/webhooks/wefunder",
+  express.raw({ type: "*/*" }),
+  async (req, res) => {
+    let event;
+    try {
+      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;
+    }
+
+    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),
+    });
+  },
+);
 ```
 
 `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.
@@ -250,6 +266,39 @@ const members = await wf.unwrap(
 
 Raw operations return `{ data, error, response }`. Passing the result to `wf.unwrap()` applies the same error handling used by the resource namespaces.
 
+## Escape hatch: `wf.request` (any path)
+
+For endpoints outside the generated surface entirely — preview-tier operations
+(e.g. partner SPVs) or operations newer than your installed SDK version —
+`wf.request()` calls any API path with the SDK's full envelope: bearer auth
+(including refresh / client_credentials re-mint on 401), the pinned
+`Wefunder-Version` header, the retry policy, and a typed `WefunderError` on
+failure. It is untyped by design; preview endpoints can change at any time.
+
+```ts
+// GET with query params
+const spvs = await wf.request("GET", "/partner/spvs", { query: { limit: 10 } });
+
+// POST with a JSON body and an idempotency key
+const session = await wf.request(
+  "POST",
+  `/partner/spvs/${spvId}/investment_sessions`,
+  {
+    body: {
+      investment_session: {
+        email: "alex@example.com",
+        allocation_cents: 500_000,
+      },
+    },
+    headers: { "Idempotency-Key": "invite-alex-1" },
+  },
+);
+```
+
+The returned body is passed through as-is (no `{ data }` unwrapping — envelope
+shapes vary across unshipped endpoints). When an operation graduates to the
+generated surface, switch to `wf.raw.<opId>` (typed) or its namespace method.
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -33,10 +33,12 @@ __export(index_exports, {
   REQUEST_ID_HEADER: () => REQUEST_ID_HEADER,
   SANDBOX_AUTHORIZE_BASE_URL: () => SANDBOX_AUTHORIZE_BASE_URL,
   SIGNATURE_HEADER: () => SIGNATURE_HEADER,
+  TokenManager: () => TokenManager,
   WebhookSignatureError: () => WebhookSignatureError,
   Wefunder: () => Wefunder,
   WefunderAuthError: () => WefunderAuthError,
   WefunderError: () => WefunderError,
+  WefunderTokenPersistenceError: () => WefunderTokenPersistenceError,
   checkWebhookSignature: () => checkWebhookSignature,
   clientCredentialsGrant: () => clientCredentialsGrant,
   collect: () => collect,
@@ -1074,6 +1076,20 @@ var WefunderAuthError = class extends WefunderError {
 };
 
 // src/token-manager.ts
+var WefunderTokenPersistenceError = class extends Error {
+  tokens;
+  constructor(tokens, cause) {
+    super(
+      `Token store failed to save the rotated token set: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause }
+    );
+    this.name = "WefunderTokenPersistenceError";
+    this.tokens = tokens;
+  }
+};
+function sameTokenSet(a, b) {
+  return a.accessToken === b.accessToken && a.refreshToken === b.refreshToken;
+}
 var TokenManager = class {
   #tokens;
   #clientId;
@@ -1086,6 +1102,7 @@ var TokenManager = class {
   #now;
   #leeway;
   #inflight;
+  #pending;
   constructor(opts) {
     this.#tokens = opts.tokens;
     this.#clientId = opts.clientId;
@@ -1098,15 +1115,40 @@ var TokenManager = class {
     this.#now = opts.now ?? Date.now;
     this.#leeway = opts.expiryLeewayMs ?? 3e4;
   }
+  /** The durable, in-use token set. A rotated set that could not be persisted sits in `pendingTokens`. */
   get current() {
     return this.#tokens;
   }
   /** True if the manager can recover an expired token (rotate a refresh token or re-mint). */
   get canRefresh() {
-    return Boolean(this.#tokens.refreshToken && this.#clientId || this.#reMint);
+    return Boolean(
+      this.#tokens.refreshToken && this.#clientId || this.#reMint
+    );
+  }
+  /** A rotated set awaiting a successful `store.save` (see `WefunderTokenPersistenceError`). */
+  get pendingTokens() {
+    return this.#pending;
   }
-  /** Returns a valid access token, refreshing proactively if it's expired/near-expiry. */
+  /**
+   * Tell the manager you persisted `tokens` (the set from a `WefunderTokenPersistenceError`)
+   * yourself. Publishes it only if it is still the pending set — a stale acknowledgment (the
+   * manager has since rotated again) is a no-op and returns false, so an older save can never
+   * publish a newer, unsaved set.
+   */
+  async markPersisted(tokens) {
+    const pending = this.#pending;
+    if (!pending || !sameTokenSet(pending, tokens)) return false;
+    this.#pending = void 0;
+    this.#tokens = pending;
+    return true;
+  }
+  /**
+   * Returns a valid access token, refreshing proactively if it's expired/near-expiry. If a
+   * rotated set is pending persistence, the save is retried first — no request uses an
+   * undurable token.
+   */
   async getAccessToken() {
+    if (this.#pending) await this.refresh();
     const { expiresAt } = this.#tokens;
     if (expiresAt !== void 0 && this.#now() >= expiresAt - this.#leeway && this.canRefresh) {
       await this.refresh();
@@ -1120,6 +1162,14 @@ var TokenManager = class {
    */
   async refresh() {
     if (this.#inflight) return this.#inflight;
+    if (this.#pending) {
+      this.#inflight = this.#publishPending();
+      try {
+        return await this.#inflight;
+      } finally {
+        this.#inflight = void 0;
+      }
+    }
     const strategy = this.#recoveryStrategy();
     if (!strategy) {
       throw new WefunderAuthError(
@@ -1127,11 +1177,8 @@ var TokenManager = class {
       );
     }
     this.#inflight = (async () => {
-      const next = await strategy();
-      this.#tokens = next;
-      await this.#store?.save(next);
-      await this.#onTokenRefresh?.(next);
-      return next;
+      this.#pending = await strategy();
+      return this.#publishPending();
     })();
     try {
       return await this.#inflight;
@@ -1139,6 +1186,22 @@ var TokenManager = class {
       this.#inflight = void 0;
     }
   }
+  // Persist BEFORE publishing: no caller may use the rotated token until it is durable, and a
+  // failed save must not leave the process working in memory but unable to reconnect after a
+  // restart. On failure the set stays pending and WefunderTokenPersistenceError is thrown; the
+  // next call retries the save.
+  async #publishPending() {
+    const tokens = this.#pending;
+    try {
+      await this.#store?.save(tokens);
+      await this.#onTokenRefresh?.(tokens);
+    } catch (err) {
+      throw new WefunderTokenPersistenceError(tokens, err);
+    }
+    this.#pending = void 0;
+    this.#tokens = tokens;
+    return tokens;
+  }
   // Pick the recovery strategy: refresh_token rotation, else cc re-mint, else none.
   #recoveryStrategy() {
     const refreshTokenValue = this.#tokens.refreshToken;
@@ -1831,12 +1894,22 @@ var Wefunder = class _Wefunder {
     });
   }
   /** The live token set (e.g. to persist after construction). */
+  /** A rotated set awaiting a successful save (see `WefunderTokenPersistenceError`). */
+  get pendingTokens() {
+    return this.#tokens.pendingTokens;
+  }
+  /** Acknowledge an out-of-band save of `tokens`; false if that set is no longer pending. */
+  markPersisted(tokens) {
+    return this.#tokens.markPersisted(tokens);
+  }
   get tokens() {
     return this.#tokens.current;
   }
   // ---- unwrap: turn the {data,error,response} result into data-or-throw ----
   async #unwrap(p) {
     const { data, error, response } = await p;
+    if (error instanceof WefunderTokenPersistenceError || error instanceof WefunderError)
+      throw error;
     if (response && response.ok && error === void 0) return data;
     const status = response?.status ?? 0;
     const env = error ?? {};
@@ -1845,7 +1918,10 @@ var Wefunder = class _Wefunder {
       type: env.error?.type ?? "api_error",
       message: env.error?.message ?? response?.statusText ?? "Request failed",
       // X-Wf-Request-Id header is primary (present even on non-JSON edge errors).
-      requestId: requestIdFrom(response, env.error?.request_id ?? env.request_id),
+      requestId: requestIdFrom(
+        response,
+        env.error?.request_id ?? env.request_id
+      ),
       details: env.error?.details,
       remediation: env.error?.remediation
     });
@@ -1871,6 +1947,32 @@ var Wefunder = class _Wefunder {
   unwrap(p) {
     return this.#unwrap(p);
   }
+  /**
+   * Untyped escape hatch: call ANY API path with the SDK's full envelope —
+   * bearer auth (incl. refresh / client_credentials re-mint on 401), the pinned
+   * `Wefunder-Version` header, the retry policy, and a typed `WefunderError` on
+   * failure. For endpoints outside the generated surface: preview-tier ops
+   * (e.g. partner SPVs) or ops newer than this SDK build.
+   *
+   * `path` is relative to the client's `baseUrl` (e.g. `"/partner/spvs"`).
+   * Returns the raw response body (no `{ data }` unwrapping — envelopes vary
+   * across unshipped endpoints).
+   */
+  async request(method, path, opts = {}) {
+    return this.#unwrap(
+      this.#client.request({
+        method,
+        url: path,
+        // Same security descriptor the generated ops pass — this is what makes
+        // the client attach (and on 401, refresh/re-mint) the bearer token.
+        security: [{ scheme: "bearer", type: "http" }],
+        query: opts.query,
+        body: opts.body,
+        // JSON by default when a body is present; caller headers win.
+        headers: opts.body !== void 0 ? { "Content-Type": "application/json", ...opts.headers } : opts.headers
+      })
+    );
+  }
   // Generic page helper: forwards the endpoint's full query (cursor + documented
   // params like `sort`), not just the cursor. (Stress-test finding B.)
   #page(fn) {
@@ -1881,11 +1983,23 @@ var Wefunder = class _Wefunder {
     me: () => this.#unwrapData(getCurrentUser({ client: this.#client }))
   };
   offerings = {
-    list: this.#page(listOfferings),
+    list: this.#page(
+      listOfferings
+    ),
     all: (query) => paginate((cursor) => this.offerings.list({ ...query, cursor })),
     collect: (query) => collect((cursor) => this.offerings.list({ ...query, cursor })),
     get: (externalId) => this.#unwrapData(
-      getOffering({ client: this.#client, path: { external_id: externalId } })
+      getOffering({
+        client: this.#client,
+        path: { external_id: externalId }
+      })
+    ),
+    /** Aggregate investment stats (count / committed / raised, by status) for one offering. */
+    stats: (externalId) => this.#unwrapData(
+      getOfferingStats({
+        client: this.#client,
+        path: { offering_id: externalId }
+      })
     )
   };
   /**
@@ -1894,20 +2008,40 @@ var Wefunder = class _Wefunder {
    * from your last page — it is always present — and resume from it next time.
    */
   investments = {
-    list: this.#page(listInvestments),
-    all: (query) => paginate((cursor) => this.investments.list({ ...query, cursor })),
-    collect: (query) => collect((cursor) => this.investments.list({ ...query, cursor })),
+    list: this.#page(
+      listInvestments
+    ),
+    all: (query) => paginate(
+      (cursor) => this.investments.list({
+        ...query,
+        cursor
+      })
+    ),
+    collect: (query) => collect(
+      (cursor) => this.investments.list({
+        ...query,
+        cursor
+      })
+    ),
     /** The current record (not the published projection) for one investment (`inv_…`). */
-    get: (id) => this.#unwrapData(getInvestment({ client: this.#client, path: { id } }))
+    get: (id) => this.#unwrapData(
+      getInvestment({ client: this.#client, path: { id } })
+    )
   };
   portfolio = {
-    get: (query) => this.#unwrapData(getPortfolio({ client: this.#client, query })),
+    get: (query) => this.#unwrapData(
+      getPortfolio({ client: this.#client, query })
+    ),
     positions: {
       list: this.#page(
         listPortfolioPositions
       ),
-      all: (query) => paginate((cursor) => this.portfolio.positions.list({ ...query, cursor })),
-      collect: (query) => collect((cursor) => this.portfolio.positions.list({ ...query, cursor }))
+      all: (query) => paginate(
+        (cursor) => this.portfolio.positions.list({ ...query, cursor })
+      ),
+      collect: (query) => collect(
+        (cursor) => this.portfolio.positions.list({ ...query, cursor })
+      )
     }
   };
   campaigns = {
@@ -1916,17 +2050,91 @@ var Wefunder = class _Wefunder {
     collect: () => collect((cursor) => this.campaigns.list({ cursor }))
   };
   syndicates = {
-    list: this.#page(listSyndicates),
+    list: this.#page(
+      listSyndicates
+    ),
     all: (query) => paginate((cursor) => this.syndicates.list({ ...query, cursor })),
-    get: (id) => this.#unwrapData(getSyndicate({ client: this.#client, path: { id } }))
+    get: (id) => this.#unwrapData(
+      getSyndicate({ client: this.#client, path: { id } })
+    )
   };
   intents = {
     list: this.#page(listIntents),
     all: (query) => paginate((cursor) => this.intents.list({ ...query, cursor })),
-    get: (id) => this.#unwrapData(getIntent({ client: this.#client, path: { id } }))
+    get: (id) => this.#unwrapData(
+      getIntent({ client: this.#client, path: { id } })
+    )
   };
   attribution = {
-    me: () => this.#unwrapData(getAttributionMe({ client: this.#client }))
+    me: () => this.#unwrapData(
+      getAttributionMe({ client: this.#client })
+    )
+  };
+  /**
+   * Installations (`/installations`, scopes `read:installations` / `write:installations`;
+   * write does not imply read). An install lets your app act AS a company or syndicate:
+   * `create` and `mintToken` return a company-owned token (shown once, no expiry, no
+   * refresh) — build a second client with it. Installing is also what makes a company
+   * or syndicate an audience for your webhooks.
+   */
+  installations = {
+    /** Companies / syndicates the token's user may install your app on (empty for an investor). */
+    eligibleTargets: (query) => this.#unwrapData(
+      listEligibleInstallTargets({ client: this.#client, query })
+    ).then((rows) => rows ?? []),
+    /** Every install of your app (`meta.count`). */
+    list: () => this.#unwrap(
+      listInstallations({ client: this.#client })
+    ),
+    get: (id) => this.#unwrapData(
+      getInstallation({
+        client: this.#client,
+        path: { external_id: id }
+      })
+    ),
+    /**
+     * Install on a target. Store `token.access_token` — it is never shown again. If the
+     * app is already installed there the API answers 409 `already_installed` with
+     * `details.installation` = the existing id; mint a token for that instead
+     * (see `installOrMintToken`).
+     */
+    create: (input) => this.#unwrap(
+      createInstallation({ client: this.#client, body: input })
+    ),
+    /**
+     * A fresh company-owned token for an existing install. `scopes` narrows within the
+     * install's ceiling; omit it for the ceiling, and note an explicit `[]` grants nothing.
+     */
+    mintToken: (id, scopes) => this.#unwrap(
+      createInstallationToken({
+        client: this.#client,
+        path: { external_id: id },
+        body: scopes ? { scopes } : void 0
+      })
+    ),
+    /**
+     * `create`, falling back to `mintToken` for the existing install on 409
+     * `already_installed`. The mint re-requests `input.scopes` so a retry never widens the
+     * grant. Any other error (revoked install, missing scope) still throws.
+     */
+    installOrMintToken: async (input) => {
+      try {
+        return await this.installations.create(input);
+      } catch (err) {
+        if (!(err instanceof WefunderError) || err.type !== "already_installed")
+          throw err;
+        const existingId = err.details?.installation;
+        if (!existingId) throw err;
+        return this.installations.mintToken(existingId, input.scopes);
+      }
+    },
+    /** Revoke an install: its tokens stop working at once. Returns the install, now `revoked`. */
+    revoke: (id) => this.#unwrapData(
+      revokeInstallation({
+        client: this.#client,
+        path: { external_id: id }
+      })
+    )
   };
   /**
    * Webhook endpoints (`/webhook_endpoints`, scopes `read:webhooks` / `write:webhooks`).
@@ -1937,30 +2145,50 @@ var Wefunder = class _Wefunder {
    */
   webhookEndpoints = {
     /** All of your app's endpoints (secret omitted). `meta.quota` is the per-app limit. */
-    list: () => this.#unwrap(listWebhookEndpoints({ client: this.#client })),
+    list: () => this.#unwrap(
+      listWebhookEndpoints({ client: this.#client })
+    ),
     get: (id) => this.#unwrapData(
-      getWebhookEndpoint({ client: this.#client, path: { external_id: id } })
+      getWebhookEndpoint({
+        client: this.#client,
+        path: { external_id: id }
+      })
     ),
     /** Store `attributes.secret` from the result — it is never shown again. */
-    create: (input) => this.#unwrapData(createWebhookEndpoint({ client: this.#client, body: input })),
+    create: (input) => this.#unwrapData(
+      createWebhookEndpoint({ client: this.#client, body: input })
+    ),
     /** `events` replaces the subscription list wholesale (no merge); omit to leave unchanged. */
     update: (id, input) => this.#unwrapData(
-      updateWebhookEndpoint({ client: this.#client, path: { external_id: id }, body: input })
+      updateWebhookEndpoint({
+        client: this.#client,
+        path: { external_id: id },
+        body: input
+      })
     ),
     /** Stops deliveries immediately. Removal is permanent — create a new endpoint to resume. */
     remove: (id) => this.#unwrapData(
-      deleteWebhookEndpoint({ client: this.#client, path: { external_id: id } })
+      deleteWebhookEndpoint({
+        client: this.#client,
+        path: { external_id: id }
+      })
     ),
     /**
      * New secret (shown once). The old one keeps signing for a 24h overlap — deliveries
      * carry a `v1` for both, and `constructEvent` accepts either.
      */
     rotateSecret: (id) => this.#unwrapData(
-      rotateWebhookEndpointSecret({ client: this.#client, path: { external_id: id } })
+      rotateWebhookEndpointSecret({
+        client: this.#client,
+        path: { external_id: id }
+      })
     ),
     /** Recover an auto-disabled endpoint after fixing your server. Idempotent. */
     reenable: (id) => this.#unwrapData(
-      reenableWebhookEndpoint({ client: this.#client, path: { external_id: id } })
+      reenableWebhookEndpoint({
+        client: this.#client,
+        path: { external_id: id }
+      })
     ),
     /**
      * POST a real, signed example event at the endpoint (production envelope + signature)
@@ -2156,10 +2384,12 @@ async function dispatchWebhook(event, handlers) {
   REQUEST_ID_HEADER,
   SANDBOX_AUTHORIZE_BASE_URL,
   SIGNATURE_HEADER,
+  TokenManager,
   WebhookSignatureError,
   Wefunder,
   WefunderAuthError,
   WefunderError,
+  WefunderTokenPersistenceError,
   checkWebhookSignature,
   clientCredentialsGrant,
   collect,