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

package/dist/index.js

@@ -1022,6 +1022,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;
@@ -1034,6 +1048,7 @@ var TokenManager = class {
   #now;
   #leeway;
   #inflight;
+  #pending;
   constructor(opts) {
     this.#tokens = opts.tokens;
     this.#clientId = opts.clientId;
@@ -1046,15 +1061,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();
@@ -1068,6 +1108,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(
@@ -1075,11 +1123,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;
@@ -1087,6 +1132,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;
@@ -1779,12 +1840,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 ?? {};
@@ -1793,7 +1864,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
     });
@@ -1819,6 +1893,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) {
@@ -1829,11 +1929,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 }
+      })
     )
   };
   /**
@@ -1842,20 +1954,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 = {
@@ -1864,17 +1996,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`).
@@ -1885,30 +2091,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)
@@ -2103,10 +2329,12 @@ export {
   REQUEST_ID_HEADER,
   SANDBOX_AUTHORIZE_BASE_URL,
   SIGNATURE_HEADER,
+  TokenManager,
   WebhookSignatureError,
   Wefunder,
   WefunderAuthError,
   WefunderError,
+  WefunderTokenPersistenceError,
   checkWebhookSignature,
   clientCredentialsGrant,
   collect,