@chrt-inc/typescript-sdk 0.1.0-beta0 → 0.226.0

package/README.md

@@ -3,7 +3,7 @@
 [![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 API from TypeScript.
+The Chrt TypeScript library provides convenient access to the Chrt APIs from TypeScript.
 
 ## Installation
 
@@ -23,7 +23,7 @@ Instantiate and use the client with the following:
 import { ChrtClient } from "@chrt-inc/typescript-sdk";
 
 const client = new ChrtClient({ token: "YOUR_TOKEN" });
-await client.dev.postTemplate({
+await client.dev.createTemplate({
     message: "message",
     number: 1,
     timestamp: "2024-01-15T09:30:00Z",
@@ -52,12 +52,13 @@ will be thrown.
 import { ChrtError } from "@chrt-inc/typescript-sdk";
 
 try {
-    await client.dev.postTemplate(...);
+    await client.dev.createTemplate(...);
 } catch (err) {
     if (err instanceof ChrtError) {
         console.log(err.statusCode);
         console.log(err.message);
         console.log(err.body);
+        console.log(err.rawResponse);
     }
 }
 ```
@@ -69,7 +70,7 @@ try {
 If you would like to send additional headers as part of the request, use the `headers` request option.
 
 ```typescript
-const response = await client.dev.postTemplate(..., {
+const response = await client.dev.createTemplate(..., {
     headers: {
         'X-Custom-Header': 'custom value'
     }
@@ -79,10 +80,10 @@ const response = await client.dev.postTemplate(..., {
 ### Retries
 
 The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
-as the request is deemed retriable and the number of retry attempts has not grown larger than the configured
+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 retriable when any of the following HTTP status codes is returned:
+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)
@@ -91,7 +92,7 @@ A request is deemed retriable when any of the following HTTP status codes is ret
 Use the `maxRetries` request option to configure this behavior.
 
 ```typescript
-const response = await client.dev.postTemplate(..., {
+const response = await client.dev.createTemplate(..., {
     maxRetries: 0 // override maxRetries at the request level
 });
 ```
@@ -101,7 +102,7 @@ const response = await client.dev.postTemplate(..., {
 The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
 
 ```typescript
-const response = await client.dev.postTemplate(..., {
+const response = await client.dev.createTemplate(..., {
     timeoutInSeconds: 30 // override timeout to 30s
 });
 ```
@@ -112,12 +113,24 @@ The SDK allows users to abort requests at any point by passing in an abort signa
 
 ```typescript
 const controller = new AbortController();
-const response = await client.dev.postTemplate(..., {
+const response = await client.dev.createTemplate(..., {
     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.dev.createTemplate(...).withRawResponse();
+
+console.log(data);
+console.log(rawResponse.headers['X-My-Header']);
+```
+
 ### Runtime Compatibility
 
 The SDK defaults to `node-fetch` but will use the global fetch client if present. The SDK works in the following
@@ -132,7 +145,7 @@ runtimes:
 
 ### Customizing Fetch Client
 
-The SDK provides a way for your to customize the underlying HTTP client / Fetch function. If you're running in an
+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
@@ -153,3 +166,393 @@ a proof of concept, but know that we will not be able to merge it as-is. We sugg
 an issue first to discuss with us!
 
 On the other hand, contributions to the README are always very welcome!
+
+## 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.milestones.images.getByMetadataId(...);
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+const stream = response.stream();
+await Bun.write('path/to/file', stream);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.milestones.images.getByMetadataId(...);
+
+const arrayBuffer = await response.arrayBuffer();
+await Bun.write('path/to/file', arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+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.milestones.images.getByMetadataId(...);
+
+const stream = response.stream();
+const text = await new Response(stream).text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>ArrayBuffer</summary>
+
+```ts
+const response = await client.milestones.images.getByMetadataId(...);
+
+const arrayBuffer = await response.arrayBuffer();
+const text = new TextDecoder().decode(arrayBuffer);
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Blob</summary>
+
+```ts
+const response = await client.milestones.images.getByMetadataId(...);
+
+const blob = await response.blob();
+const text = await blob.text();
+```
+
+</details>
+</blockquote>
+
+<blockquote>
+<details>
+<summary>Bytes (UIntArray8)</summary>
+
+```ts
+const response = await client.milestones.images.getByMetadataId(...);
+
+const bytes = await response.bytes();
+const text = new TextDecoder().decode(bytes);
+```
+
+</details>
+</blockquote>
+
+</details>

package/dist/cjs/Client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as environments from "./environments.js";
+import * as core from "./core/index.js";
+import { Dev } from "./api/resources/dev/client/Client.js";
+import { Drivers } from "./api/resources/drivers/client/Client.js";
+import { Milestones } from "./api/resources/milestones/client/Client.js";
+import { OffChrtShipperOrgInfo } from "./api/resources/offChrtShipperOrgInfo/client/Client.js";
+import { OrgProfiles } from "./api/resources/orgProfiles/client/Client.js";
+import { Orders } from "./api/resources/orders/client/Client.js";
+import { CourierPayDriverRateSheets } from "./api/resources/courierPayDriverRateSheets/client/Client.js";
+import { ShipperPayCourierRateSheets } from "./api/resources/shipperPayCourierRateSheets/client/Client.js";
+import { CourierPayDriverLineItemGroups } from "./api/resources/courierPayDriverLineItemGroups/client/Client.js";
+import { ShipperPayCourierLineItemGroups } from "./api/resources/shipperPayCourierLineItemGroups/client/Client.js";
+import { ShipperPayCourierPayments } from "./api/resources/shipperPayCourierPayments/client/Client.js";
+import { CourierPayDriverPayouts } from "./api/resources/courierPayDriverPayouts/client/Client.js";
+import { Connections } from "./api/resources/connections/client/Client.js";
+import { TaskGroups } from "./api/resources/taskGroups/client/Client.js";
+import { ShipperContactInfo } from "./api/resources/shipperContactInfo/client/Client.js";
+import { MilestoneNotifications } from "./api/resources/milestoneNotifications/client/Client.js";
+import { Orgs } from "./api/resources/orgs/client/Client.js";
+import { Payments } from "./api/resources/payments/client/Client.js";
+import { Root } from "./api/resources/root/client/Client.js";
+import { Users } from "./api/resources/users/client/Client.js";
+import { Utils } from "./api/resources/utils/client/Client.js";
+import { Notifications } from "./api/resources/notifications/client/Client.js";
+import { OrgConnectionInfos } from "./api/resources/orgConnectionInfos/client/Client.js";
+export declare namespace ChrtClient {
+    interface Options {
+        environment?: core.Supplier<environments.ChrtEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
+        token?: core.Supplier<core.BearerToken | undefined>;
+        /** Additional headers to include in requests. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+        fetcher?: core.FetchFunction;
+    }
+    interface RequestOptions {
+        /** The maximum time to wait for a response in seconds. */
+        timeoutInSeconds?: number;
+        /** The number of times to retry the request. Defaults to 2. */
+        maxRetries?: number;
+        /** A hook to abort the request. */
+        abortSignal?: AbortSignal;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+    }
+}
+export declare class ChrtClient {
+    protected readonly _options: ChrtClient.Options;
+    protected _dev: Dev | undefined;
+    protected _drivers: Drivers | undefined;
+    protected _milestones: Milestones | undefined;
+    protected _offChrtShipperOrgInfo: OffChrtShipperOrgInfo | undefined;
+    protected _orgProfiles: OrgProfiles | undefined;
+    protected _orders: Orders | undefined;
+    protected _courierPayDriverRateSheets: CourierPayDriverRateSheets | undefined;
+    protected _shipperPayCourierRateSheets: ShipperPayCourierRateSheets | undefined;
+    protected _courierPayDriverLineItemGroups: CourierPayDriverLineItemGroups | undefined;
+    protected _shipperPayCourierLineItemGroups: ShipperPayCourierLineItemGroups | undefined;
+    protected _shipperPayCourierPayments: ShipperPayCourierPayments | undefined;
+    protected _courierPayDriverPayouts: CourierPayDriverPayouts | undefined;
+    protected _connections: Connections | undefined;
+    protected _taskGroups: TaskGroups | undefined;
+    protected _shipperContactInfo: ShipperContactInfo | undefined;
+    protected _milestoneNotifications: MilestoneNotifications | undefined;
+    protected _orgs: Orgs | undefined;
+    protected _payments: Payments | undefined;
+    protected _root: Root | undefined;
+    protected _users: Users | undefined;
+    protected _utils: Utils | undefined;
+    protected _notifications: Notifications | undefined;
+    protected _orgConnectionInfos: OrgConnectionInfos | undefined;
+    constructor(_options?: ChrtClient.Options);
+    get dev(): Dev;
+    get drivers(): Drivers;
+    get milestones(): Milestones;
+    get offChrtShipperOrgInfo(): OffChrtShipperOrgInfo;
+    get orgProfiles(): OrgProfiles;
+    get orders(): Orders;
+    get courierPayDriverRateSheets(): CourierPayDriverRateSheets;
+    get shipperPayCourierRateSheets(): ShipperPayCourierRateSheets;
+    get courierPayDriverLineItemGroups(): CourierPayDriverLineItemGroups;
+    get shipperPayCourierLineItemGroups(): ShipperPayCourierLineItemGroups;
+    get shipperPayCourierPayments(): ShipperPayCourierPayments;
+    get courierPayDriverPayouts(): CourierPayDriverPayouts;
+    get connections(): Connections;
+    get taskGroups(): TaskGroups;
+    get shipperContactInfo(): ShipperContactInfo;
+    get milestoneNotifications(): MilestoneNotifications;
+    get orgs(): Orgs;
+    get payments(): Payments;
+    get root(): Root;
+    get users(): Users;
+    get utils(): Utils;
+    get notifications(): Notifications;
+    get orgConnectionInfos(): OrgConnectionInfos;
+}