@metronome/sdk 0.3.0 → 2.0.0

package/CHANGELOG.md

@@ -1,46 +1,131 @@
 # Changelog
 
-## 0.3.0 (2025-08-15)
+## 2.0.0 (2025-10-16)
+
+Full Changelog: [v1.0.0...v2.0.0](https://github.com/Metronome-Industries/metronome-node/compare/v1.0.0...v2.0.0)
+
+### ⚠ BREAKING CHANGES
+
+* **api:** Remove customer_id from preview events payload
+* **api:** in getEditHistory endpoint, commit invoice schedule amount, unit price, and quantity are now optional values
+* **api:** Added optional archive_filter param to /notifications/offset/list endpoint
+
+### Features
+
+* Add empty handler for cancelPayment ([8a9f2e8](https://github.com/Metronome-Industries/metronome-node/commit/8a9f2e800db4f6d977d8fade405836f91cf0ca9f))
+* Add payment + billing invoice APIs to the API reference docs ([8cd1d7a](https://github.com/Metronome-Industries/metronome-node/commit/8cd1d7a4678a3887a60fe26c6e6bda89fa4b9bec))
+* Add payment APIs to the SDK ([0adfefc](https://github.com/Metronome-Industries/metronome-node/commit/0adfefc9acf0ab3d480041495f2726446efb9cb4))
+* **api:** add billing_periods to Subscription ([9498382](https://github.com/Metronome-Industries/metronome-node/commit/9498382c48d925d2dc52fb5286d302009371751a))
+* **api:** add new payments/attempt v1 api endpoint ([51234ab](https://github.com/Metronome-Industries/metronome-node/commit/51234abdd9de4ed0a2733b3333e936abec7a4301))
+* **api:** Added optional archive_filter param to /notifications/offset/list endpoint ([efb0aa1](https://github.com/Metronome-Industries/metronome-node/commit/efb0aa188a8c2df9ec025e0f666886f3efd381a0))
+* **api:** Remove customer_id from preview events payload ([d80600b](https://github.com/Metronome-Industries/metronome-node/commit/d80600b4f3be4f9cfc3b94f6acbd13184c7e5c31))
+* Bump graphql version and fix type errors ([a6349d5](https://github.com/Metronome-Industries/metronome-node/commit/a6349d555d194b13a8f6fec4092e01dd49a4f7d4))
+* elia/orch 128 add external apis for payments ([637dc77](https://github.com/Metronome-Industries/metronome-node/commit/637dc77cdf4847ab2ab8458fc06f243d878db724))
+* feat(api):Allow clients retrieve archived config via `/notifications/get` ([ab0b0b1](https://github.com/Metronome-Industries/metronome-node/commit/ab0b0b10ab2102da479552ee5fc3155382085dbd))
+* internal: releasing x-mint ([6f0209a](https://github.com/Metronome-Industries/metronome-node/commit/6f0209a8aa776c96b61ca7bc93ad95b0704009b6))
+* internal: Skip retrieve_pdf API SDK tests ([47426e8](https://github.com/Metronome-Industries/metronome-node/commit/47426e8fea7aa2194c3e31d243becbda73295551))
+* internal(docs): adding confluent endpoints ([66682c2](https://github.com/Metronome-Industries/metronome-node/commit/66682c2705aa432cf5b42bf6c02da3aebbbc187b))
+* LAUNCH-516 add getSubscriptionSeatsScheduleHistory api ([87bffd4](https://github.com/Metronome-Industries/metronome-node/commit/87bffd4eef2a8bbe890d1efcdfddfd351236fa22))
+* **mcp:** add docs search tool ([5b2bce7](https://github.com/Metronome-Industries/metronome-node/commit/5b2bce751297111cae257591faa3da4546ff5065))
+* **mcp:** add option for including docs tools ([4e51097](https://github.com/Metronome-Industries/metronome-node/commit/4e51097669b68a0c473659530ff5920272db1559))
+* **mcp:** enable experimental docs search tool ([9f3a19d](https://github.com/Metronome-Industries/metronome-node/commit/9f3a19d6fd24629865c90ec943be13066929724c))
+* rename getSubscriptionSeatsScheduleHistory to getSubscriptionSeatsHistory ([2a45a7e](https://github.com/Metronome-Industries/metronome-node/commit/2a45a7ecf906d1e07d5530385138590f940626f7))
+* Return array of invoices instead of single invoice and handle multipl… ([843ca4c](https://github.com/Metronome-Industries/metronome-node/commit/843ca4c0cbb15c4bcb13a66ce783452adbad9316))
+* Set up contract get and create with new AH info ([2a15df8](https://github.com/Metronome-Industries/metronome-node/commit/2a15df82e9595ba74d5ca3625d8a582bd9838cb6))
+* update api docs ([ddc0510](https://github.com/Metronome-Industries/metronome-node/commit/ddc0510f876f3cdea0456301c0ec6ef4548100b5))
+
+
+### Bug Fixes
+
+* **api:** in getEditHistory endpoint, commit invoice schedule amount, unit price, and quantity are now optional values ([df927b1](https://github.com/Metronome-Industries/metronome-node/commit/df927b13491689eeb4fa6db96d0989c2e14b76d2))
+* **ci:** set permissions for DXT publish action ([b1bcdad](https://github.com/Metronome-Industries/metronome-node/commit/b1bcdadbf37415497c02cd83e38695be81ac7b44))
+* LAUNCH-1130 remove min and max in api spec for better valiation error message ([20b4d2c](https://github.com/Metronome-Industries/metronome-node/commit/20b4d2cba2d177a71bed7f9db62faabab028cc81))
+* **mcp:** fix cli argument parsing logic ([6db4b4a](https://github.com/Metronome-Industries/metronome-node/commit/6db4b4af661841fe68536cc086a270ea9b93d71f))
+
+
+### Performance Improvements
+
+* faster formatting ([08badd1](https://github.com/Metronome-Industries/metronome-node/commit/08badd16ee6d0a3594977c68540a233fabac163a))
+
+
+### Chores
+
+* **codegen:** internal codegen update ([1dc34a9](https://github.com/Metronome-Industries/metronome-node/commit/1dc34a9cc5066a72c19cfd382472d607effcde75))
+* do not install brew dependencies in ./scripts/bootstrap by default ([607b9b0](https://github.com/Metronome-Industries/metronome-node/commit/607b9b0ada5cb004718cd31c074333c6d9870bdf))
+* extract some types in mcp docs ([2f279f4](https://github.com/Metronome-Industries/metronome-node/commit/2f279f4edb3881f5b4b4ab8577497159915c6680))
+* **internal:** codegen related update ([dde1c3b](https://github.com/Metronome-Industries/metronome-node/commit/dde1c3bababf9ce3b224aa0bd8f69e6a395548e3))
+* **internal:** fix incremental formatting in some cases ([e6aa27e](https://github.com/Metronome-Industries/metronome-node/commit/e6aa27e75896fc2b10f8f0c3f890c839c812afc0))
+* **internal:** gitignore .mcpb files ([0e48487](https://github.com/Metronome-Industries/metronome-node/commit/0e48487bcbd06f3230acd0d9ffa44f9d684d2ae5))
+* **internal:** ignore .eslintcache ([63e1f8e](https://github.com/Metronome-Industries/metronome-node/commit/63e1f8e459f108f4f5d10e2e3a93c64ec090b006))
+* **internal:** remove .eslintcache ([68b87db](https://github.com/Metronome-Industries/metronome-node/commit/68b87dbb06b8b2d3ca403a713434b6daf4a6170b))
+* **internal:** remove deprecated `compilerOptions.baseUrl` from tsconfig.json ([da007e0](https://github.com/Metronome-Industries/metronome-node/commit/da007e0a5e459e623ed8fe8f9b255a70f29532d4))
+* **internal:** use npm pack for build uploads ([610d7b1](https://github.com/Metronome-Industries/metronome-node/commit/610d7b191822a83c6afdd9c4b67859a14b05f653))
+* **jsdoc:** fix [@link](https://github.com/link) annotations to refer only to parts of the package‘s public interface ([2192205](https://github.com/Metronome-Industries/metronome-node/commit/21922059a1991ea558e77aea79993685f873167f))
+* **mcp:** allow pointing `docs_search` tool at other URLs ([996112b](https://github.com/Metronome-Industries/metronome-node/commit/996112b87d1cf2cd7421f49143f40762e4b0b656))
+* **mcp:** rename dxt to mcpb ([f57db37](https://github.com/Metronome-Industries/metronome-node/commit/f57db3729eadc05ce4b806ff8748540abb7b04ff))
+* update lockfile ([1657600](https://github.com/Metronome-Industries/metronome-node/commit/16576000f23fe49205c7d4d9842416627a7ffbad))
+
+## 1.0.0 (2025-09-15)
+
+Full Changelog: [v0.3.0...v1.0.0](https://github.com/Metronome-Industries/metronome-node/compare/v0.3.0...v1.0.0)
+
+### ⚠ BREAKING CHANGES
+
+* **api:** add pagination support to multiple endpoints - Added pagination to CustomerList, AlertList, InvoiceList, CommitList, CreditList, CreditGrantList, CustomerAlerts, UsageList, CustomFields list, and ContractListBalances endpoints.
+* **api:** enhance subscriptions and commits/credits - Added Individual enum to SubscriptionConfig and rate_type enums to UpdateCredit/UpdateCommit.
+* **typescript-sdk:** migrate to latest SDK version - Migrated TypeScript SDK with improved type safety, enhanced error handling, updated method signatures, and restructured package exports. Existing TypeScript SDK integrations will require updates to import paths, method calls, and configuration options. See our Migration Guide for detailed step-by-step instructions.
+* **api:** add comprehensive shared types to SDK - Added 34 new shared types including BaseThresholdCommit, BaseUsageFilter, Commit, CommitHierarchyConfiguration, CommitRate, CommitSpecifier, CommitSpecifierInput, Contract, ContractV2, ContractWithoutAmendments, Credit, CreditTypeData, Discount, EventTypeFilter, HierarchyConfiguration, ID, Override, OverrideTier, OverwriteRate, PaymentGateConfig, PaymentGateConfigV2, PrepaidBalanceThresholdConfiguration, PrepaidBalanceThresholdConfigurationV2, PropertyFilter, ProService, Rate, RecurringCommitSubscriptionConfig, ScheduledCharge, ScheduleDuration, SchedulePointInTime, SpendThresholdConfiguration, SpendThresholdConfigurationV2, Subscription, Tier, and UpdateBaseThresholdCommit.
+
+### Features
+
+* **api:** add archived_at field to CustomerBillingConfiguration ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **api:** add comprehensive shared types to SDK - Added 34 new shared types including BaseThresholdCommit, BaseUsageFilter, Commit, CommitHierarchyConfiguration, CommitRate, CommitSpecifier, CommitSpecifierInput, Contract, ContractV2, ContractWithoutAmendments, Credit, CreditTypeData, Discount, EventTypeFilter, HierarchyConfiguration, ID, Override, OverrideTier, OverwriteRate, PaymentGateConfig, PaymentGateConfigV2, PrepaidBalanceThresholdConfiguration, PrepaidBalanceThresholdConfigurationV2, PropertyFilter, ProService, Rate, RecurringCommitSubscriptionConfig, ScheduledCharge, ScheduleDuration, SchedulePointInTime, SpendThresholdConfiguration, SpendThresholdConfigurationV2, Subscription, Tier, and UpdateBaseThresholdCommit. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **api:** add created_at field to Commit ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **api:** add customer billing configuration endpoints - Added set and retrieve endpoints for customer billing configurations. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **api:** add pagination support to multiple endpoints - Added pagination to CustomerList, AlertList, InvoiceList, CommitList, CreditList, CreditGrantList, CustomerAlerts, UsageList, CustomFields list, and ContractListBalances endpoints. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **api:** Add support for granular spend threshold alerts with group key filters. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **api:** enhance subscriptions and commits/credits - Added Individual enum to SubscriptionConfig and rate_type enums to UpdateCredit/UpdateCommit. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **typescript-sdk:** migrate to latest SDK version - Migrated TypeScript SDK with improved type safety, enhanced error handling, updated method signatures, and restructured package exports. Existing TypeScript SDK integrations will require updates to import paths, method calls, and configuration options. See our Migration Guide for detailed step-by-step instructions. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+
+
+### Bug Fixes
+
+* **mcp:** fix query options parsing ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+* **mcp:** fix uploading dxt release assets ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+
+
+### Chores
+
+* coerce nullable values to undefined ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+
+
+### Documentation
+
+* enhance API documentation - Added more detailed descriptions and styling improvements, and enhanced usage filter documentation with additional context. ([70c82e0](https://github.com/Metronome-Industries/metronome-node/commit/70c82e0b5b0df3a3031f6a4264c0d00e063bf868))
+
+## 0.3.0 (2025-09-15)
 
 Full Changelog: [v0.2.0...v0.3.0](https://github.com/Metronome-Industries/metronome-node/compare/v0.2.0...v0.3.0)
 
 ### Features
 
-* **api:** api update ([e884b86](https://github.com/Metronome-Industries/metronome-node/commit/e884b866e9c4cae020b420a52a13e3e37af0a0e1))
-* **api:** api update ([b35e26a](https://github.com/Metronome-Industries/metronome-node/commit/b35e26a035a6ef7c61bb5291702c93b3ee121d43))
-* **api:** api update ([6683cf9](https://github.com/Metronome-Industries/metronome-node/commit/6683cf99275e575b188cc1d6a01d688e53f201b4))
-* **api:** api update ([a36d626](https://github.com/Metronome-Industries/metronome-node/commit/a36d62641e01ad7c36f91d7371a4988a2b05f0a4))
-* **api:** api update ([c865ee1](https://github.com/Metronome-Industries/metronome-node/commit/c865ee1b48e7cecd86b9ef1bcec61d83e0d8cbde))
-* **api:** api update ([62d4fd8](https://github.com/Metronome-Industries/metronome-node/commit/62d4fd845d64b162596d2f2e2ef300daf4d4b5c0))
-* **api:** api update ([ce43e12](https://github.com/Metronome-Industries/metronome-node/commit/ce43e1222870d9842786230a2adab43433326e39))
-* **api:** api update ([734bfdc](https://github.com/Metronome-Industries/metronome-node/commit/734bfdcdea00e42709d8d655a7f71f532f1db980))
-* **api:** api update ([9538819](https://github.com/Metronome-Industries/metronome-node/commit/9538819f0d9289cbdc3f13e8337843af47845194))
-* **api:** api update ([7658522](https://github.com/Metronome-Industries/metronome-node/commit/76585227332f5bf7f7640af83cc56a791972afbc))
-* **api:** api update ([39508d4](https://github.com/Metronome-Industries/metronome-node/commit/39508d435f1966327cadcf4f208f8e7bbd65e902))
-* **mcp:** add logging when environment variable is set ([da446ed](https://github.com/Metronome-Industries/metronome-node/commit/da446ed9e30f4f8b2d75c73346583388f53fda80))
-* **mcp:** add unix socket option for remote MCP ([1bb6f63](https://github.com/Metronome-Industries/metronome-node/commit/1bb6f63c9f0c2b7c24d3c768fba5bf1dbd451563))
-* **mcp:** remote server with passthru auth ([0c61cb9](https://github.com/Metronome-Industries/metronome-node/commit/0c61cb95a43ba9e4046f2c4026800e95802a76f4))
+* **api:** api update ([6053d58](https://github.com/Metronome-Industries/metronome-node/commit/6053d586c4fc67e770fad2f9bc9de1706ec363a7))
+* **api:** api update ([1be7b2d](https://github.com/Metronome-Industries/metronome-node/commit/1be7b2d4cc78f10f17cd4021287410c4996900ac))
+* **api:** api update ([fcc3172](https://github.com/Metronome-Industries/metronome-node/commit/fcc3172129d07d7da715b4982acbfb96664f7518))
 
 
 ### Bug Fixes
 
-* **mcp:** fix bug in header handling ([bbc7303](https://github.com/Metronome-Industries/metronome-node/commit/bbc730360ef3559a2d261dbf60329d59c4f5fe1a))
-* **mcp:** fix jq type bug ([3e1050a](https://github.com/Metronome-Industries/metronome-node/commit/3e1050a46b81373576a6a24118b9feb514d08a2e))
-* **mcp:** generate additionalProperties=true for map schemas to avoid validation issues ([4e3ef3f](https://github.com/Metronome-Industries/metronome-node/commit/4e3ef3f3119c7098b2001747fda4ab5320ff03e8))
+* coerce nullable values to undefined ([db26826](https://github.com/Metronome-Industries/metronome-node/commit/db268263220cb5cacfd6a55ff04de39d2477b323))
+* **mcp:** fix query options parsing ([a680969](https://github.com/Metronome-Industries/metronome-node/commit/a68096999d241b3a6dff06115a76e9c1bacb2fbe))
+* **mcp:** fix uploading dxt release assets ([d2bd1f5](https://github.com/Metronome-Industries/metronome-node/commit/d2bd1f5b6640c9bebf047089347401a2786046d4))
 
 
 ### Chores
 
-* **deps:** update dependency node-fetch to v2.6.13 ([9b7cc9f](https://github.com/Metronome-Industries/metronome-node/commit/9b7cc9fb05969c27013f79aa28556620b2b4aaf9))
-* **internal:** formatting change ([56e19ef](https://github.com/Metronome-Industries/metronome-node/commit/56e19efd00d1adcd0871f05c4cb4ec4176f7c669))
-* **internal:** move publish config ([7fe7728](https://github.com/Metronome-Industries/metronome-node/commit/7fe77288030502d813786a2c2cd90ebd45a5a2ce))
-* **internal:** update comment in script ([eb4b678](https://github.com/Metronome-Industries/metronome-node/commit/eb4b6789b92c39cc300b915050f5212684c79b3b))
-* **mcp:** bump JQ version ([cd9db46](https://github.com/Metronome-Industries/metronome-node/commit/cd9db463c3def01355a92b724de723c91dfbbce1))
-* **mcp:** document remote server in README.md ([4858f2f](https://github.com/Metronome-Industries/metronome-node/commit/4858f2faae46abd6998b931900399a332f46adfa))
-* **mcp:** minor cleanup of types and package.json ([b1c81f4](https://github.com/Metronome-Industries/metronome-node/commit/b1c81f46ec293036ae154d3f73fc1563c09f3336))
-* **mcp:** refactor streamable http transport ([26ea8ca](https://github.com/Metronome-Industries/metronome-node/commit/26ea8ca90308a338dd46786e68c63c2d37642c59))
-* **mcp:** update README ([fd863d9](https://github.com/Metronome-Industries/metronome-node/commit/fd863d9ac0acfbd6743dc5668f0343405a378388))
-* update @stainless-api/prism-cli to v5.15.0 ([5ce7a05](https://github.com/Metronome-Industries/metronome-node/commit/5ce7a053d4a88bde83fa560ac1636934f742fe68))
+* **internal:** codegen related update ([191878f](https://github.com/Metronome-Industries/metronome-node/commit/191878f4c0c324365353e04f32dcdb12db6d5308))
+* **mcp:** upload dxt as release asset ([870849d](https://github.com/Metronome-Industries/metronome-node/commit/870849d07517ee4e94c9d5f6afc05c46d1a71958))
+* sync repo ([86f91c5](https://github.com/Metronome-Industries/metronome-node/commit/86f91c5d57c205949c945d058c931353b64147fa))
 
 ## 0.2.0 (2025-07-31)
 

package/README.md

@@ -1,6 +1,6 @@
-# Metronome Node API Library
+# Metronome TypeScript API Library
 
-[![NPM version](https://img.shields.io/npm/v/@metronome/sdk.svg)](https://npmjs.org/package/@metronome/sdk) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@metronome/sdk)
+[![NPM version](<https://img.shields.io/npm/v/@metronome/sdk.svg?label=npm%20(stable)>)](https://npmjs.org/package/@metronome/sdk) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@metronome/sdk)
 
 This library provides convenient access to the Metronome REST API from server-side TypeScript or JavaScript.
 
@@ -24,15 +24,17 @@ const client = new Metronome({
   bearerToken: process.env['METRONOME_BEARER_TOKEN'], // This is the default and can be omitted
 });
 
-await client.v1.usage.ingest([
-  {
-    transaction_id: '90e9401f-0f8c-4cd3-9a9f-d6beb56d8d72',
-    customer_id: 'team@example.com',
-    event_type: 'heartbeat',
-    timestamp: '2024-01-01T00:00:00Z',
-    properties: { cluster_id: '42', cpu_seconds: 60, region: 'Europe' },
-  },
-]);
+await client.v1.usage.ingest({
+  usage: [
+    {
+      transaction_id: '90e9401f-0f8c-4cd3-9a9f-d6beb56d8d72',
+      customer_id: 'team@example.com',
+      event_type: 'heartbeat',
+      timestamp: '2024-01-01T00:00:00Z',
+      properties: { cluster_id: '42', cpu_seconds: 60, region: 'Europe' },
+    },
+  ],
+});
 ```
 
 ### Request & Response types
@@ -168,8 +170,10 @@ while (page.hasNextPage()) {
 ### 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
@@ -188,6 +192,59 @@ console.log(raw.headers.get('X-My-Header'));
 console.log(contract.data);
 ```
 
+### 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 `METRONOME_LOG` environment variable
+2. Using the `logLevel` client option (overrides the environment variable if set)
+
+```ts
+import Metronome from '@metronome/sdk';
+
+const client = new Metronome({
+  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 Metronome from '@metronome/sdk';
+import pino from 'pino';
+
+const logger = pino();
+
+const client = new Metronome({
+  logger: logger.child({ name: 'Metronome' }),
+  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
@@ -212,9 +269,8 @@ parameter. This library doesn't validate at runtime that the request matches the
 send will be sent as-is.
 
 ```ts
-client.foo.create({
-  foo: 'my_param',
-  bar: 12,
+client.v1.usage.ingest({
+  // ...
   // @ts-expect-error baz is not yet public
   baz: 'undocumented option',
 });
@@ -234,69 +290,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 "Metronome"`:
+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 '@metronome/sdk/shims/web';
-import Metronome from '@metronome/sdk';
+import fetch from 'my-fetch';
+
+globalThis.fetch = fetch;
 ```
 
-To do the inverse, add `import "@metronome/sdk/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/Metronome-Industries/metronome-node/tree/main/src/_shims#readme)).
+Or pass it to the client:
+
+```ts
+import Metronome from '@metronome/sdk';
+import fetch from 'my-fetch';
+
+const client = new Metronome({ 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 Metronome from '@metronome/sdk';
 
 const client = new Metronome({
-  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 Metronome from '@metronome/sdk';
+import * as undici from 'undici';
+
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
+const client = new Metronome({
+  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 Metronome from '@metronome/sdk';
 
-// Configure the default for all requests:
 const client = new Metronome({
-  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
+  },
 });
+```
 
-// Override per-request:
-await client.v1.contracts.create(
-  { customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', starting_at: '2020-01-01T00:00:00.000Z' },
-  {
-    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 Metronome from 'npm:@metronome/sdk';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const client = new Metronome({
+  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:
@@ -311,12 +383,12 @@ We are keen for your feedback; please open an [issue](https://www.github.com/Met
 
 ## 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,2 @@
+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":""}

package/api-promise.d.ts

@@ -0,0 +1,2 @@
+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":""}

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,2 @@
+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":""}

package/bin/cli

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+
+const commands = {
+  migrate: {
+    description: 'Run migrations to update your code using @metronome/sdk@0.3.0 to be compatible with @metronome/sdk@1.0.0',
+    fn: () => {
+      const result = spawnSync(
+        'npx',
+        ['-y', 'https://github.com/stainless-api/migrate-ts/releases/download/0.0.2/stainless-api-migrate-0.0.2-6.tgz', '--migrationConfig', require.resolve('./migration-config.json'), ...process.argv.slice(3)],
+        { stdio: 'inherit' },
+      );
+      if (result.status !== 0) {
+        process.exit(result.status);
+      }
+    }
+  }
+}
+
+function exitWithHelp() {
+  console.log(`Usage: metronome-sdk <subcommand>`);
+  console.log();
+  console.log('Subcommands:');
+
+  for (const [name, info] of Object.entries(commands)) {
+    console.log(`  ${name}  ${info.description}`);
+  }
+
+  console.log();
+  process.exit(1);
+}
+
+if (process.argv.length < 3) {
+  exitWithHelp();
+}
+
+const commandName = process.argv[2];
+
+const command = commands[commandName];
+if (!command) {
+  console.log(`Unknown subcommand ${commandName}.`);
+  exitWithHelp();
+}
+
+command.fn();

package/bin/migration-config.json

@@ -0,0 +1,6 @@
+{
+  "pkg": "@metronome/sdk",
+  "githubRepo": "https://github.com/Metronome-Industries/metronome-node",
+  "clientClass": "Metronome",
+  "methods": []
+}