@tolt/api 1.1.0 → 1.3.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.3.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options?.headers);

package/dist/Client.d.ts

@@ -6,6 +6,7 @@ import { FlowsClient } from "./api/resources/flows/client/Client.js";
 import { GroupsClient } from "./api/resources/groups/client/Client.js";
 import { LinksClient } from "./api/resources/links/client/Client.js";
 import { PartnersClient } from "./api/resources/partners/client/Client.js";
+import { PartnerTagsClient } from "./api/resources/partnerTags/client/Client.js";
 import { ProgramsClient } from "./api/resources/programs/client/Client.js";
 import { PromotionCodesClient } from "./api/resources/promotionCodes/client/Client.js";
 import { ReportsClient } from "./api/resources/reports/client/Client.js";
@@ -25,6 +26,7 @@ export declare class ToltApiClient {
     protected _flows: FlowsClient | undefined;
     protected _clicks: ClicksClient | undefined;
     protected _partners: PartnersClient | undefined;
+    protected _partnerTags: PartnerTagsClient | undefined;
     protected _programs: ProgramsClient | undefined;
     protected _customers: CustomersClient | undefined;
     protected _commissions: CommissionsClient | undefined;
@@ -38,6 +40,7 @@ export declare class ToltApiClient {
     get flows(): FlowsClient;
     get clicks(): ClicksClient;
     get partners(): PartnersClient;
+    get partnerTags(): PartnerTagsClient;
     get programs(): ProgramsClient;
     get customers(): CustomersClient;
     get commissions(): CommissionsClient;

package/dist/Client.js

@@ -7,6 +7,7 @@ import { FlowsClient } from "./api/resources/flows/client/Client.js";
 import { GroupsClient } from "./api/resources/groups/client/Client.js";
 import { LinksClient } from "./api/resources/links/client/Client.js";
 import { PartnersClient } from "./api/resources/partners/client/Client.js";
+import { PartnerTagsClient } from "./api/resources/partnerTags/client/Client.js";
 import { ProgramsClient } from "./api/resources/programs/client/Client.js";
 import { PromotionCodesClient } from "./api/resources/promotionCodes/client/Client.js";
 import { ReportsClient } from "./api/resources/reports/client/Client.js";
@@ -32,6 +33,9 @@ export class ToltApiClient {
     get partners() {
         return (this._partners ??= new PartnersClient(this._options));
     }
+    get partnerTags() {
+        return (this._partnerTags ??= new PartnerTagsClient(this._options));
+    }
     get programs() {
         return (this._programs ??= new ProgramsClient(this._options));
     }

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/index.d.ts

@@ -22,6 +22,9 @@ export * from "./links/types/index.js";
 export * from "./partners/client/requests/index.js";
 export * as partners from "./partners/index.js";
 export * from "./partners/types/index.js";
+export * from "./partnerTags/client/requests/index.js";
+export * as partnerTags from "./partnerTags/index.js";
+export * from "./partnerTags/types/index.js";
 export * from "./programs/client/requests/index.js";
 export * as programs from "./programs/index.js";
 export * from "./programs/types/index.js";

package/dist/api/resources/index.js

@@ -22,6 +22,9 @@ export * from "./links/types/index.js";
 export * from "./partners/client/requests/index.js";
 export * as partners from "./partners/index.js";
 export * from "./partners/types/index.js";
+export * from "./partnerTags/client/requests/index.js";
+export * as partnerTags from "./partnerTags/index.js";
+export * from "./partnerTags/types/index.js";
 export * from "./programs/client/requests/index.js";
 export * as programs from "./programs/index.js";
 export * from "./programs/types/index.js";

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

@@ -0,0 +1,118 @@
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth } from "../../../../BaseClient.js";
+import * as core from "../../../../core/index.js";
+import * as ToltApi from "../../../index.js";
+export declare namespace PartnerTagsClient {
+    type Options = BaseClientOptions;
+    interface RequestOptions extends BaseRequestOptions {
+    }
+}
+export declare class PartnerTagsClient {
+    protected readonly _options: NormalizedClientOptionsWithAuth<PartnerTagsClient.Options>;
+    constructor(options: PartnerTagsClient.Options);
+    /**
+     * Lists the tags you can put on partners. Filter by program, search by name, and page with cursors.
+     *
+     * @param {ToltApi.ListPartnerTagsRequest} request
+     * @param {PartnerTagsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link ToltApi.BadRequestError}
+     * @throws {@link ToltApi.UnauthorizedError}
+     * @throws {@link ToltApi.ContentTooLargeError}
+     * @throws {@link ToltApi.TooManyRequestsError}
+     * @throws {@link errors.ToltApiError}
+     * @throws {@link errors.ToltApiTimeoutError}
+     *
+     * @example
+     *     await client.partnerTags.listPartnerTags()
+     */
+    listPartnerTags(request?: ToltApi.ListPartnerTagsRequest, requestOptions?: PartnerTagsClient.RequestOptions): core.HttpResponsePromise<ToltApi.ListPartnerTagsResponse>;
+    private __listPartnerTags;
+    /**
+     * Creates a tag in a program. Put it on partners with POST /v2/partners/{id}/tags.
+     *
+     * @param {ToltApi.CreatePartnerTagRequest} request
+     * @param {PartnerTagsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link ToltApi.BadRequestError}
+     * @throws {@link ToltApi.UnauthorizedError}
+     * @throws {@link ToltApi.ConflictError}
+     * @throws {@link ToltApi.ContentTooLargeError}
+     * @throws {@link ToltApi.TooManyRequestsError}
+     * @throws {@link errors.ToltApiError}
+     * @throws {@link errors.ToltApiTimeoutError}
+     *
+     * @example
+     *     await client.partnerTags.createPartnerTag({
+     *         program_id: "prg_T6z8aRW3XCmvFWP972RKxpAd",
+     *         name: "VIP",
+     *         color: "#2457D6"
+     *     })
+     */
+    createPartnerTag(request: ToltApi.CreatePartnerTagRequest, requestOptions?: PartnerTagsClient.RequestOptions): core.HttpResponsePromise<ToltApi.CreatePartnerTagResponse>;
+    private __createPartnerTag;
+    /**
+     * Gets a partner tag by ID, with how many partners have it.
+     *
+     * @param {ToltApi.GetPartnerTagRequest} request
+     * @param {PartnerTagsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link ToltApi.UnauthorizedError}
+     * @throws {@link ToltApi.NotFoundError}
+     * @throws {@link ToltApi.ContentTooLargeError}
+     * @throws {@link ToltApi.TooManyRequestsError}
+     * @throws {@link errors.ToltApiError}
+     * @throws {@link errors.ToltApiTimeoutError}
+     *
+     * @example
+     *     await client.partnerTags.getPartnerTag({
+     *         id: "ptag_zDEcdqNuNBPcokarWxBnk9gB"
+     *     })
+     */
+    getPartnerTag(request: ToltApi.GetPartnerTagRequest, requestOptions?: PartnerTagsClient.RequestOptions): core.HttpResponsePromise<ToltApi.GetPartnerTagResponse>;
+    private __getPartnerTag;
+    /**
+     * Renames a tag or changes its color. Partners who have the tag keep it.
+     *
+     * @param {ToltApi.UpdatePartnerTagRequest} request
+     * @param {PartnerTagsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link ToltApi.BadRequestError}
+     * @throws {@link ToltApi.UnauthorizedError}
+     * @throws {@link ToltApi.NotFoundError}
+     * @throws {@link ToltApi.ConflictError}
+     * @throws {@link ToltApi.ContentTooLargeError}
+     * @throws {@link ToltApi.TooManyRequestsError}
+     * @throws {@link errors.ToltApiError}
+     * @throws {@link errors.ToltApiTimeoutError}
+     *
+     * @example
+     *     await client.partnerTags.updatePartnerTag({
+     *         id: "ptag_zDEcdqNuNBPcokarWxBnk9gB",
+     *         name: "VIP",
+     *         color: "#2457D6"
+     *     })
+     */
+    updatePartnerTag(request: ToltApi.UpdatePartnerTagRequest, requestOptions?: PartnerTagsClient.RequestOptions): core.HttpResponsePromise<ToltApi.UpdatePartnerTagResponse>;
+    private __updatePartnerTag;
+    /**
+     * Deletes a tag and removes it from every partner who has it.
+     *
+     * @param {ToltApi.DeletePartnerTagRequest} request
+     * @param {PartnerTagsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link ToltApi.UnauthorizedError}
+     * @throws {@link ToltApi.NotFoundError}
+     * @throws {@link ToltApi.ContentTooLargeError}
+     * @throws {@link ToltApi.TooManyRequestsError}
+     * @throws {@link errors.ToltApiError}
+     * @throws {@link errors.ToltApiTimeoutError}
+     *
+     * @example
+     *     await client.partnerTags.deletePartnerTag({
+     *         id: "ptag_zDEcdqNuNBPcokarWxBnk9gB"
+     *     })
+     */
+    deletePartnerTag(request: ToltApi.DeletePartnerTagRequest, requestOptions?: PartnerTagsClient.RequestOptions): core.HttpResponsePromise<ToltApi.DeletePartnerTagResponse>;
+    private __deletePartnerTag;
+}