@wefunder/sdk 0.1.0-beta.11 → 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

@@ -1947,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) {
@@ -1967,6 +1993,13 @@ var Wefunder = class _Wefunder {
         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 }
+      })
     )
   };
   /**
@@ -2037,6 +2070,72 @@ var Wefunder = class _Wefunder {
       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`).
    * Endpoints belong to your application and are managed through the LIVE API —