@tolt/api 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @tolt/api
 
-TypeScript SDK for the [Tolt](https://tolt.com) public API (v2). Generated from our OpenAPI spec with [Fern](https://buildwithfern.com); do not edit by hand.
+TypeScript SDK for the Tolt API (v2). Run it on your server: it needs your secret API key. Requires Node 18 or newer.
 
 ## Install
 
@@ -13,25 +13,53 @@ npm install @tolt/api
 ```ts
 import { ToltApiClient } from "@tolt/api";
 
-const client = new ToltApiClient({
-  baseUrl: "https://api.tolt.com",
-  token: process.env.TOLT_API_KEY!, // your Tolt API key
-});
+const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY! });
 
-const transactions = await client.transactions.list();
-const overview = await client.reports.overview();
-const clicks = await client.clicks.list();
+const { data: partner } = await tolt.partners.get({ id: "part_8fKq2LmZx7RtYw3nVbHc5dPj" });
+
+for await (const customer of await tolt.customers.list()) {
+  console.log(customer.id);
+}
 ```
 
-Sub-clients cover the whole API: `transactions`, `commissions`, `customers`, `partners`, `programs`, `links`, `promotionCodes`, `groups`, `flows`, `clicks`, `reports`. Every path, request, and response is typed from the spec.
+Single-item calls return the API envelope, so read `.data`. `list` returns a page: iterate it with `for await` to walk every page, or read `page.data` for one page.
 
-## Build
+Resources: `partners`, `customers`, `transactions`, `commissions`, `links`, `clicks`, `promotionCodes`, `programs`, `groups`, `flows`, `reports`, `embedTokens`.
 
-```bash
-npm install   # runs the build via the prepare script
-npm run build # -> dist/
+## Errors
+
+```ts
+import { ToltApi, ToltApiError, ToltApiTimeoutError } from "@tolt/api";
+
+try {
+  await tolt.partners.get({ id: "part_8fKq2LmZx7RtYw3nVbHc5dPj" });
+} catch (err) {
+  if (err instanceof ToltApi.NotFoundError) {
+    // err.body.code === "not_found"
+  } else if (err instanceof ToltApiTimeoutError) {
+    // no response within timeoutInSeconds
+  } else if (err instanceof ToltApiError) {
+    console.error(err.statusCode, err.body, err.requestId);
+  }
+}
+```
+
+## Retries and timeouts
+
+Failed requests (408, 429, 5xx) are retried twice with backoff. Calls that create something (every `create`, and `transactions.rerunFlows`) are never retried, so a server error can't create a duplicate. Override per client or per call:
+
+```ts
+const tolt = new ToltApiClient({ token: process.env.TOLT_API_KEY!, maxRetries: 3, timeoutInSeconds: 30 });
 ```
 
-## Regenerating
+The client talks to `https://platform.tolt.com` by default. Pass `baseUrl` to point it elsewhere.
+
+## Development
 
-This package is generated. Regenerate it from the OpenAPI spec in the `tolt-sdks-v2` Fern workspace (`fern generate --local`).
+`src/` is generated by [Fern](https://buildwithfern.com) from the API's OpenAPI spec in [toltapp/tolt-sdks](https://github.com/toltapp/tolt-sdks), which opens a pull request here when the spec changes. Don't edit `src/` by hand.
+
+```bash
+npm ci
+npm run build
+npm test
+```

package/dist/BaseClient.js

@@ -5,7 +5,7 @@ import * as core from "./core/index.js";
 export function normalizeClientOptions(options) {
     const headers = mergeHeaders({
         "X-Fern-Language": "JavaScript",
-        "User-Agent": "tolt-typescript/1.1.0",
+        "User-Agent": "tolt-typescript/1.2.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options?.headers);

package/dist/api/resources/embedTokens/client/Client.d.ts

@@ -11,7 +11,7 @@ export declare class EmbedTokensClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<EmbedTokensClient.Options>;
     constructor(options: EmbedTokensClient.Options);
     /**
-     * Mint a short-lived, partner-scoped token for the embedded referral dashboard. Safe to send to the browser.
+     * Mint a short-lived, partner-scoped token for the embedded referral dashboard. Safe to send to the browser. With partner (email and program_id), the partner is created when the program has none with that email, so one call covers a user's first visit.
      *
      * @param {ToltApi.CreateEmbedTokenRequest} request
      * @param {EmbedTokensClient.RequestOptions} requestOptions - Request-specific configuration.

package/dist/api/resources/embedTokens/client/Client.js

@@ -12,7 +12,7 @@ export class EmbedTokensClient {
         this._options = normalizeClientOptionsWithAuth(options);
     }
     /**
-     * Mint a short-lived, partner-scoped token for the embedded referral dashboard. Safe to send to the browser.
+     * Mint a short-lived, partner-scoped token for the embedded referral dashboard. Safe to send to the browser. With partner (email and program_id), the partner is created when the program has none with that email, so one call covers a user's first visit.
      *
      * @param {ToltApi.CreateEmbedTokenRequest} request
      * @param {EmbedTokensClient.RequestOptions} requestOptions - Request-specific configuration.

package/dist/api/resources/embedTokens/client/requests/CreateEmbedTokenRequest.d.ts

@@ -5,17 +5,23 @@
 export interface CreateEmbedTokenRequest {
     /** Id of an existing partner (part_...). Send this or partner, not both. */
     partner_id?: string;
-    /** Look up an onboarded partner by email within a program. Send this or partner_id, not both. */
+    /** Find the partner by email within the program, or create them (active, with a referral link) when the program has no partner with that email. Send this or partner_id, not both. */
     partner?: CreateEmbedTokenRequest.Partner;
 }
 export declare namespace CreateEmbedTokenRequest {
     /**
-     * Look up an onboarded partner by email within a program. Send this or partner_id, not both.
+     * Find the partner by email within the program, or create them (active, with a referral link) when the program has no partner with that email. Send this or partner_id, not both.
      */
     interface Partner {
         /** Email of the partner, matched without regard to case. */
         email: string;
         /** Program the partner belongs to (prg_...). */
         program_id: string;
+        /** First name, used only when the partner is created. */
+        first_name?: string | undefined;
+        /** Last name, used only when the partner is created. */
+        last_name?: string | undefined;
+        /** Group for a newly created partner. Defaults to the program's default group. */
+        group_id?: string | undefined;
     }
 }

package/dist/api/resources/transactions/client/requests/CreateTransactionRequest.d.ts

@@ -17,7 +17,7 @@ export interface CreateTransactionRequest {
     product_id?: string;
     /** Readable name of the purchased product, such as Pro plan. It is saved as the transaction's product name, which revenue_by_product groups revenue by; flows match on product_id, not on this name. */
     product_name?: string;
-    /** The payment amount in the smallest unit of the program currency (cents for USD); percentage commissions are calculated from it. */
+    /** The payment amount in the smallest unit of the program currency (cents for USD); percentage commissions are calculated from it. It must be 0 or more: to reverse a payment, refund its transaction instead of recording a negative amount. */
     amount: number;
     /** Id of the customer who paid (cus_...), as returned when listing customers. The transaction goes to that customer's partner and program, and the customer becomes active. */
     customer_id: string;

package/dist/api/types/EmbedToken.d.ts

@@ -1,4 +1,6 @@
 export interface EmbedToken {
     token: string;
     expires_at: string;
+    /** The partner the token is for, including one this call just created. */
+    partner_id: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolt/api",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "TypeScript SDK for the Tolt Public API",
   "license": "Apache-2.0",
   "repository": {