@chrt-inc/typescript-sdk 1.304.0 → 1.306.0

package/README.md

@@ -0,0 +1,585 @@
+# Chrt TypeScript Library
+
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fchrt-inc%2Ftypescript-sdk)
+[![npm shield](https://img.shields.io/npm/v/@chrt-inc/typescript-sdk)](https://www.npmjs.com/package/@chrt-inc/typescript-sdk)
+
+The Chrt TypeScript library provides convenient access to the Chrt APIs from TypeScript.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Reference](#reference)
+- [Usage](#usage)
+- [Request and Response Types](#request-and-response-types)
+- [Exception Handling](#exception-handling)
+- [Binary Response](#binary-response)
+- [Advanced](#advanced)
+    - [Additional Headers](#additional-headers)
+    - [Additional Query String Parameters](#additional-query-string-parameters)
+    - [Retries](#retries)
+    - [Timeouts](#timeouts)
+    - [Aborting Requests](#aborting-requests)
+    - [Access Raw Response Data](#access-raw-response-data)
+    - [Runtime Compatibility](#runtime-compatibility)
+- [Contributing](#contributing)
+
+## Installation
+
+```sh
+npm i -s @chrt-inc/typescript-sdk
+```
+
+## Reference
+
+A full reference for this library is available [here](https://github.com/chrt-inc/typescript-sdk/blob/HEAD/./reference.md).
+
+## Usage
+
+Instantiate and use the client with the following:
+
+```typescript
+import { ChrtClient } from "@chrt-inc/typescript-sdk";
+
+const client = new ChrtClient({ token: "YOUR_TOKEN" });
+await client.payments.generateInvoiceV1({
+    shipper_pay_courier_statement_id: "shipper_pay_courier_statement_id",
+});
+```
+
+## Request and Response Types
+
+The SDK exports all request and response types as TypeScript interfaces. Simply import them with the
+following namespace:
+
+```typescript
+import { Chrt } from "@chrt-inc/typescript-sdk";
+
+const request: Chrt.GenerateInvoiceReq = {
+    ...
+};
+```
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
+
+```typescript
+import { ChrtError } from "@chrt-inc/typescript-sdk";
+
+try {
+    await client.payments.generateInvoiceV1(...);
+} catch (err) {
+    if (err instanceof ChrtError) {
+        console.log(err.statusCode);
+        console.log(err.message);
+        console.log(err.body);
+        console.log(err.rawResponse);
+    }
+}
+```
+
+## Binary Response
+
+You can consume binary data from endpoints using the `BinaryResponse` type which lets you choose how to consume the data:
+
+```typescript
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+const stream: ReadableStream<Uint8Array> = response.stream();
+// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
+// const blob: Blob = response.blob();
+// const bytes: Uint8Array = response.bytes();
+// You can only use the response body once, so you must choose one of the above methods.
+// If you want to check if the response body has been used, you can use the following property.
+const bodyUsed = response.bodyUsed;
+```
+
+<details>
+<summary>Save binary response to a file</summary>
+
+<blockquote>
+<details>
+<summary>Node.js</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+import { createWriteStream } from 'fs';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const stream = response.stream();
+const nodeStream = Readable.fromWeb(stream);
+const writeStream = createWriteStream('path/to/file');
+
+await pipeline(nodeStream, writeStream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await writeFile('path/to/file', Buffer.from(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const blob = await response.blob();
+const arrayBuffer = await blob.arrayBuffer();
+await writeFile('output.bin', Buffer.from(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+import { writeFile } from 'fs/promises';
+
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const bytes = await response.bytes();
+await writeFile('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bun</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const stream = response.stream();
+await Bun.write('path/to/file', stream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Bun.write('path/to/file', arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const blob = await response.blob();
+await Bun.write('path/to/file', blob);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const bytes = await response.bytes();
+await Bun.write('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Deno</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream (most-efficient)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const stream = response.stream();
+const file = await Deno.open('path/to/file', { write: true, create: true });
+await stream.pipeTo(file.writable);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const blob = await response.blob();
+const arrayBuffer = await blob.arrayBuffer();
+await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const bytes = await response.bytes();
+await Deno.writeFile('path/to/file', bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Browser</summary>
+
+<blockquote>
+<details>
+<summary>Blob (most-efficient)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const blob = await response.blob();
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ReadableStream</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const stream = response.stream();
+const reader = stream.getReader();
+const chunks = [];
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  chunks.push(value);
+}
+
+const blob = new Blob(chunks);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const blob = new Blob([arrayBuffer]);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const bytes = await response.bytes();
+const blob = new Blob([bytes]);
+const url = URL.createObjectURL(blob);
+
+// trigger download
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+</details>
+</blockquote>
+
+<details>
+<summary>Convert binary response to text</summary>
+
+<blockquote>
+<details>
+<summary>ReadableStream</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const stream = response.stream();
+const text = await new Response(stream).text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const text = new TextDecoder().decode(arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const blob = await response.blob();
+const text = await blob.text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.taskArtifacts.images.getByMetadataIdV1(...);
+
+const bytes = await response.bytes();
+const text = new TextDecoder().decode(bytes);
+```
+
+</details>
+</blockquote>
+
+</details>
+
+## Advanced
+
+### Additional Headers
+
+If you would like to send additional headers as part of the request, use the `headers` request option.
+
+```typescript
+const response = await client.payments.generateInvoiceV1(..., {
+    headers: {
+        'X-Custom-Header': 'custom value'
+    }
+});
+```
+
+### Additional Query String Parameters
+
+If you would like to send additional query string parameters as part of the request, use the `queryParams` request option.
+
+```typescript
+const response = await client.payments.generateInvoiceV1(..., {
+    queryParams: {
+        'customQueryParamKey': 'custom query param value'
+    }
+});
+```
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
+
+Use the `maxRetries` request option to configure this behavior.
+
+```typescript
+const response = await client.payments.generateInvoiceV1(..., {
+    maxRetries: 0 // override maxRetries at the request level
+});
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
+
+```typescript
+const response = await client.payments.generateInvoiceV1(..., {
+    timeoutInSeconds: 30 // override timeout to 30s
+});
+```
+
+### Aborting Requests
+
+The SDK allows users to abort requests at any point by passing in an abort signal.
+
+```typescript
+const controller = new AbortController();
+const response = await client.payments.generateInvoiceV1(..., {
+    abortSignal: controller.signal
+});
+controller.abort(); // aborts the request
+```
+
+### Access Raw Response Data
+
+The SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.
+The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.
+
+```typescript
+const { data, rawResponse } = await client.payments.generateInvoiceV1(...).withRawResponse();
+
+console.log(data);
+console.log(rawResponse.headers['X-My-Header']);
+```
+
+### Runtime Compatibility
+
+The SDK works in the following runtimes:
+
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
+
+### Customizing Fetch Client
+
+The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an
+unsupported environment, this provides a way for you to break glass and ensure the SDK works.
+
+```typescript
+import { ChrtClient } from "@chrt-inc/typescript-sdk";
+
+const client = new ChrtClient({
+    ...
+    fetcher: // provide your implementation here
+});
+```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!

package/dist/cjs/Client.js

@@ -71,8 +71,8 @@ class ChrtClient {
         this._options = Object.assign(Object.assign({}, _options), { headers: (0, headers_js_1.mergeHeaders)({
                 "X-Fern-Language": "JavaScript",
                 "X-Fern-SDK-Name": "@chrt-inc/typescript-sdk",
-                "X-Fern-SDK-Version": "1.304.0",
-                "User-Agent": "@chrt-inc/typescript-sdk/1.304.0",
+                "X-Fern-SDK-Version": "1.306.0",
+                "User-Agent": "@chrt-inc/typescript-sdk/1.306.0",
                 "X-Fern-Runtime": core.RUNTIME.type,
                 "X-Fern-Runtime-Version": core.RUNTIME.version,
             }, _options === null || _options === void 0 ? void 0 : _options.headers) });

package/dist/cjs/api/resources/drivers/client/Client.d.ts

@@ -31,7 +31,7 @@ export declare class Drivers {
     protected readonly _options: Drivers.Options;
     constructor(_options?: Drivers.Options);
     /**
-     * Lists all organization members paired with their driver information if they are drivers.
+     * Lists all organization members paired with their driver information if they are drivers. | () -> (list[OrgMembersAndDrivers])
      *
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -41,7 +41,7 @@ export declare class Drivers {
     listOrgMembersAndDriversV1(requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<Chrt.OrgMembersAndDrivers[]>;
     private __listOrgMembersAndDriversV1;
     /**
-     * Lists all drivers belonging to the authenticated organization.
+     * Lists all drivers belonging to the authenticated organization. | () -> (list[Driver1])
      *
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -51,7 +51,7 @@ export declare class Drivers {
     listV1(requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<Chrt.Driver1[]>;
     private __listV1;
     /**
-     * Creates a new driver profile for an organization member with optional vehicle type assignments.
+     * Creates a new driver profile for an organization member with optional vehicle type assignments. | (DriverCreateReq) -> (PydanticObjectId)
      *
      * @param {Chrt.DriverCreateReq} request
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
@@ -69,7 +69,7 @@ export declare class Drivers {
     createV1(request: Chrt.DriverCreateReq, requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<string>;
     private __createV1;
     /**
-     * Retrieves driver information for the authenticated user within their organization.
+     * Retrieves driver information for the authenticated user within their organization. | () -> (Driver1)
      *
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -79,7 +79,7 @@ export declare class Drivers {
     getV1(requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<Chrt.Driver1>;
     private __getV1;
     /**
-     * Retrieves detailed driver information by driver ID within the organization.
+     * Retrieves detailed driver information by driver ID within the organization. | () -> (Driver1)
      *
      * @param {string} driverId
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
@@ -92,7 +92,7 @@ export declare class Drivers {
     getByDriverIdV1(driverId: string, requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<Chrt.Driver1>;
     private __getByDriverIdV1;
     /**
-     * Deletes a driver from the organization and removes them from associated rate sheets.
+     * Deletes a driver from the organization and removes them from associated rate sheets. | () -> (bool)
      *
      * @param {string} driverId
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
@@ -105,7 +105,7 @@ export declare class Drivers {
     deleteV1(driverId: string, requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<boolean>;
     private __deleteV1;
     /**
-     * Sets the activation status of a driver (active/inactive) within the organization.
+     * Sets the activation status of a driver (active/inactive) within the organization. | (SetDriverActivationReq) -> (bool)
      *
      * @param {Chrt.SetDriverActivationReq} request
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
@@ -121,7 +121,7 @@ export declare class Drivers {
     setActivationV1(request: Chrt.SetDriverActivationReq, requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<boolean>;
     private __setActivationV1;
     /**
-     * Updates the driver's last known location and timestamp for tracking purposes.
+     * Updates the driver's last known location and timestamp for tracking purposes. | (DriverLastSeenReq) -> (bool)
      *
      * @param {Chrt.DriverLastSeenReq} request
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
@@ -145,7 +145,7 @@ export declare class Drivers {
     lastSeenV1(request: Chrt.DriverLastSeenReq, requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<boolean>;
     private __lastSeenV1;
     /**
-     * Clears the driver's last known location and timestamp.
+     * Clears the driver's last known location and timestamp. | () -> (bool)
      *
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.
      *
@@ -155,7 +155,7 @@ export declare class Drivers {
     lastSeenClearV1(requestOptions?: Drivers.RequestOptions): core.HttpResponsePromise<boolean>;
     private __lastSeenClearV1;
     /**
-     * Updates driver contact details and vehicle type assignments within the organization.
+     * Updates driver contact details and vehicle type assignments within the organization. | (UpdateDriverDetailsReq) -> (bool)
      *
      * @param {Chrt.UpdateDriverDetailsReq} request
      * @param {Drivers.RequestOptions} requestOptions - Request-specific configuration.