orb-billing 5.76.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [6.0.0](https://github.com/orbcorp/orb-typescript/compare/v0.0.1...v6.0.0) (2026-07-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* migrate to the Stainless v2 TypeScript SDK architecture
+
+### Features
+
+* **api:** add `commitment` credit block source and `credit_commitment` field ([d1f8312](https://github.com/orbcorp/orb-typescript/commit/d1f8312062f5b9e9516fb417e29402300aa6aadc))
+* **api:** api update ([6b4bd4e](https://github.com/orbcorp/orb-typescript/commit/6b4bd4ed03ac1b5ecc574d1313e540f21e940572))
+* **api:** deprecate debug mode ingestion response field ([18c531f](https://github.com/orbcorp/orb-typescript/commit/18c531faf3f7d420eac8e8653a61a094625d2734))
+* migrate to the Stainless v2 TypeScript SDK architecture ([f32a385](https://github.com/orbcorp/orb-typescript/commit/f32a3852b64420184e17b5330221749db9358600))
+* **webhooks:** add webhook signature verification helpers ([582880e](https://github.com/orbcorp/orb-typescript/commit/582880e92cfaa9a9bbf66b1ab813936f62b4f81f))
+
+
+### Chores
+
+* import the orb-billing v5 changelog for release continuity ([12c761b](https://github.com/orbcorp/orb-typescript/commit/12c761b9927417e95cbe1fe33d9ad3ea46b13963))
+* **internal:** format ported workflows ([928c2b0](https://github.com/orbcorp/orb-typescript/commit/928c2b0f2f8122c1ec2c1e2a727b48d858b7d89f))
+* **internal:** format trunk sync lock workflow ([9e39337](https://github.com/orbcorp/orb-typescript/commit/9e39337be39becc1c1b7e02f9074367d4bdda167))
+* **internal:** stage release wiring and v1 migration tooling ([189d378](https://github.com/orbcorp/orb-typescript/commit/189d37846a0075d1f22dba564f20f35c88f0c620))
+
 ## [5.76.0](https://github.com/orbcorp/orb-node/compare/v5.75.1...v5.76.0) (2026-07-14)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Orb TypeScript API Library
 
-[![NPM version](https://img.shields.io/npm/v/orb-billing.svg)](https://npmjs.org/package/orb-billing) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/orb-billing)
+[![NPM version](<https://img.shields.io/npm/v/orb-billing.svg?label=npm%20(stable)>)](https://npmjs.org/package/orb-billing) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/orb-billing)
 
 This library provides convenient access to the Orb REST API from server-side TypeScript or JavaScript.
 
@@ -9,9 +9,12 @@ The REST API documentation can be found on [docs.withorb.com](https://docs.witho
 ## Installation
 
 ```sh
-npm install orb-billing
+npm install git+ssh://git@github.com:orbcorp/orb-typescript.git
 ```
 
+> [!NOTE]
+> Once this package is [published to npm](https://www.stainless.com/docs/guides/publish), this will become: `npm install orb-billing`
+
 ## Usage
 
 The full API of this library can be found in [api.md](api.md).
@@ -194,8 +197,10 @@ export default async function POST(req) {
 ### Accessing raw Response data (e.g., headers)
 
 The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
+This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
 
 You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
+Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
 
 <!-- prettier-ignore -->
 ```ts
@@ -214,6 +219,59 @@ console.log(raw.headers.get('X-My-Header'));
 console.log(customer.id);
 ```
 
+### Logging
+
+> [!IMPORTANT]
+> All log messages are intended for debugging only. The format and content of log messages
+> may change between releases.
+
+#### Log levels
+
+The log level can be configured in two ways:
+
+1. Via the `ORB_LOG` environment variable
+2. Using the `logLevel` client option (overrides the environment variable if set)
+
+```ts
+import Orb from 'orb-billing';
+
+const client = new Orb({
+  logLevel: 'debug', // Show all log messages
+});
+```
+
+Available log levels, from most to least verbose:
+
+- `'debug'` - Show debug messages, info, warnings, and errors
+- `'info'` - Show info messages, warnings, and errors
+- `'warn'` - Show warnings and errors (default)
+- `'error'` - Show only errors
+- `'off'` - Disable all logging
+
+At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
+Some authentication-related headers are redacted, but sensitive data in request and response bodies
+may still be visible.
+
+#### Custom logger
+
+By default, this library logs to `globalThis.console`. You can also provide a custom logger.
+Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+
+When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
+below the configured level will not be sent to your logger.
+
+```ts
+import Orb from 'orb-billing';
+import pino from 'pino';
+
+const logger = pino();
+
+const client = new Orb({
+  logger: logger.child({ name: 'Orb' }),
+  logLevel: 'debug', // Send all messages to pino, allowing it to filter
+});
+```
+
 ### Making custom/undocumented requests
 
 This library is typed for convenient access to the documented API. If you need to access undocumented
@@ -231,16 +289,15 @@ await client.post('/some/path', {
 });
 ```
 
-#### Undocumented params
+#### Undocumented request params
 
 To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented
 parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you
 send will be sent as-is.
 
 ```ts
-client.foo.create({
-  foo: 'my_param',
-  bar: 12,
+client.customers.create({
+  // ...
   // @ts-expect-error baz is not yet public
   baz: 'undocumented option',
 });
@@ -252,7 +309,7 @@ extra param in the body.
 If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request
 options.
 
-#### Undocumented properties
+#### Undocumented response properties
 
 To access undocumented response properties, you may access the response object with `// @ts-expect-error` on
 the response object, or cast the response object to the requisite type. Like the request params, we do not
@@ -260,69 +317,85 @@ validate or strip extra properties from the response from the API.
 
 ### Customizing the fetch client
 
-By default, this library uses `node-fetch` in Node, and expects a global `fetch` function in other environments.
+By default, this library expects a global `fetch` function is defined.
 
-If you would prefer to use a global, web-standards-compliant `fetch` function even in a Node environment,
-(for example, if you are running Node with `--experimental-fetch` or using NextJS which polyfills with `undici`),
-add the following import before your first import `from "Orb"`:
+If you want to use a different `fetch` function, you can either polyfill the global:
 
 ```ts
-// Tell TypeScript and the package to use the global web fetch instead of node-fetch.
-// Note, despite the name, this does not add any polyfills, but expects them to be provided if needed.
-import 'orb-billing/shims/web';
-import Orb from 'orb-billing';
+import fetch from 'my-fetch';
+
+globalThis.fetch = fetch;
 ```
 
-To do the inverse, add `import "orb-billing/shims/node"` (which does import polyfills).
-This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](https://github.com/orbcorp/orb-node/tree/main/src/_shims#readme)).
+Or pass it to the client:
+
+```ts
+import Orb from 'orb-billing';
+import fetch from 'my-fetch';
+
+const client = new Orb({ fetch });
+```
 
-### Logging and middleware
+### Fetch options
 
-You may also provide a custom `fetch` function when instantiating the client,
-which can be used to inspect or alter the `Request` or `Response` before/after each request:
+If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
 
 ```ts
-import { fetch } from 'undici'; // as one example
 import Orb from 'orb-billing';
 
 const client = new Orb({
-  fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => {
-    console.log('About to make a request', url, init);
-    const response = await fetch(url, init);
-    console.log('Got response', response);
-    return response;
+  fetchOptions: {
+    // `RequestInit` options
   },
 });
 ```
 
-Note that if given a `DEBUG=true` environment variable, this library will log all requests and responses automatically.
-This is intended for debugging purposes only and may change in the future without notice.
+#### Configuring proxies
 
-### Configuring an HTTP(S) Agent (e.g., for proxies)
+To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
+options to requests:
 
-By default, this library uses a stable agent for all http/https requests to reuse TCP connections, eliminating many TCP & TLS handshakes and shaving around 100ms off most requests.
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
 
-If you would like to disable or customize this behavior, for example to use the API behind a proxy, you can pass an `httpAgent` which is used for all requests (be they http or https), for example:
+```ts
+import Orb from 'orb-billing';
+import * as undici from 'undici';
+
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
+const client = new Orb({
+  fetchOptions: {
+    dispatcher: proxyAgent,
+  },
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
 
-<!-- prettier-ignore -->
 ```ts
-import http from 'http';
-import { HttpsProxyAgent } from 'https-proxy-agent';
+import Orb from 'orb-billing';
 
-// Configure the default for all requests:
 const client = new Orb({
-  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
+  },
 });
+```
 
-// Override per-request:
-await client.customers.create(
-  { email: 'example-customer@withorb.com', name: 'My Customer' },
-  {
-    httpAgent: new http.Agent({ keepAlive: false }),
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+
+```ts
+import Orb from 'npm:orb-billing';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const client = new Orb({
+  fetchOptions: {
+    client: httpClient,
   },
-);
+});
 ```
 
+## Frequently Asked Questions
+
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
@@ -333,16 +406,16 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience.
 
-We are keen for your feedback; please open an [issue](https://www.github.com/orbcorp/orb-node/issues) with questions, bugs, or suggestions.
+We are keen for your feedback; please open an [issue](https://www.github.com/orbcorp/orb-typescript/issues) with questions, bugs, or suggestions.
 
 ## Requirements
 
-TypeScript >= 4.5 is supported.
+TypeScript >= 4.9 is supported.
 
 The following runtimes are supported:
 
 - Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
+- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
 - Deno v1.28.0 or higher.
 - Bun 1.0 or later.
 - Cloudflare Workers.

package/api-promise.d.mts

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/api-promise instead */
+export * from "./core/api-promise.mjs";
+//# sourceMappingURL=api-promise.d.mts.map

package/api-promise.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.d.mts","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,uCAAmC"}

package/api-promise.d.ts

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/api-promise instead */
+export * from "./core/api-promise.js";
+//# sourceMappingURL=api-promise.d.ts.map

package/api-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.d.ts","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,sCAAmC"}

package/api-promise.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("./internal/tslib.js");
+/** @deprecated Import from ./core/api-promise instead */
+tslib_1.__exportStar(require("./core/api-promise.js"), exports);
+//# sourceMappingURL=api-promise.js.map

package/api-promise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.js","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,gEAAmC"}

package/api-promise.mjs

@@ -0,0 +1,3 @@
+/** @deprecated Import from ./core/api-promise instead */
+export * from "./core/api-promise.mjs";
+//# sourceMappingURL=api-promise.mjs.map

package/api-promise.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.mjs","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,uCAAmC"}