meterflow 0.4.2 → 0.4.4

package/README.md

@@ -212,6 +212,17 @@ await client.usage.recordBatch([
 ]);
 ```
 
+A batch holds at most **500 events** (exported as `MAX_BATCH_EVENTS`). A larger array is rejected locally with `PayloadTooLargeError` before anything is sent — the SDK deliberately does **not** split it for you, because one call is one request with one idempotency key, and turning it into several would make a partial failure indistinguishable from success. Chunk at the call site and give each chunk its own key:
+
+```typescript
+import { MAX_BATCH_EVENTS } from "meterflow";
+
+for (let i = 0; i < events.length; i += MAX_BATCH_EVENTS) {
+  const chunk = events.slice(i, i + MAX_BATCH_EVENTS);
+  await client.usage.recordBatch(chunk, { idempotencyKey: `job-42:chunk-${i / MAX_BATCH_EVENTS}` });
+}
+```
+
 **Summary** — a customer's usage, broken down by meter:
 
 ```typescript
@@ -324,7 +335,8 @@ Every non-2xx response is thrown as a typed error. All of them extend `MeterFlow
 | `InsufficientCreditsError` | 402 | `insufficient_credits` | no |
 | `NotFoundError` | 404 | `not_found` | no |
 | `ConflictError` | 409 | `conflict` | no |
-| `ValidationError` | 422 | `validation_error` | no |
+| `PayloadTooLargeError` | 413 | `payload_too_large` | no — split the batch (see `MAX_BATCH_EVENTS`) |
+| `ValidationError` | 422 | `validation_error` | no — per-field detail in `.fields` |
 | `RateLimitError` | 429 | `rate_limit` | yes (honours `Retry-After`, exposed as `.retryAfter`) |
 | `ServerError` | 5xx | `server_error` | yes |
 
@@ -332,6 +344,7 @@ Every error carries:
 
 - **`requestId`** — the API's `X-Request-ID` for that call. Include it when contacting support; it pinpoints the exact request in our logs.
 - **`statusCode`**, **`errorType`**, and **`retryable`** — for programmatic handling and structured logging.
+- **`message`** — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 5,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`{ field, message }[]`).
 
 ```typescript
 import { MeterFlowError, InsufficientCreditsError, RateLimitError } from "meterflow";

package/dist/errors.d.ts

@@ -17,7 +17,21 @@ export declare class InsufficientCreditsError extends MeterFlowError {
 export declare class ConflictError extends MeterFlowError {
     constructor(message: string, requestId?: string);
 }
+/** One field the API rejected, as returned in a 422's `error.fields`. */
+export interface ValidationFieldError {
+    field: string;
+    message: string;
+}
 export declare class ValidationError extends MeterFlowError {
+    /** Per-field detail from the API. Empty when the 422 carried none. */
+    readonly fields: ValidationFieldError[];
+    constructor(message: string, requestId?: string, fields?: ValidationFieldError[]);
+}
+/**
+ * The request was well-formed but too large — today only `usage.recordBatch` with more than
+ * `MAX_BATCH_EVENTS` events. Never retried: the same payload would be refused again. Split it.
+ */
+export declare class PayloadTooLargeError extends MeterFlowError {
     constructor(message: string, requestId?: string);
 }
 export declare class RateLimitError extends MeterFlowError {

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAQ5G;AAED,qBAAa,SAAU,SAAQ,cAAc;gBAC/B,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,SAAM;CAIlE;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,wBAAyB,SAAQ,cAAc;gBAC9C,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,eAAgB,SAAQ,cAAc;gBACrC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,cAAe,SAAQ,cAAc;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAKrE;AAED,qBAAa,WAAY,SAAQ,cAAc;gBACjC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,SAAM;CAIlE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAQ5G;AAED,qBAAa,SAAU,SAAQ,cAAc;gBAC/B,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,SAAM;CAIlE;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,wBAAyB,SAAQ,cAAc;gBAC9C,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,yEAAyE;AACzE,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,cAAc;IACjD,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,GAAE,oBAAoB,EAAO;CAKrF;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;gBAC1C,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAIhD;AAED,qBAAa,cAAe,SAAQ,cAAc;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAKrE;AAED,qBAAa,WAAY,SAAQ,cAAc;gBACjC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,UAAU,SAAM;CAIlE"}

package/dist/index.cjs

@@ -23,15 +23,20 @@ __export(index_exports, {
   AuthError: () => AuthError,
   ConflictError: () => ConflictError,
   InsufficientCreditsError: () => InsufficientCreditsError,
+  MAX_BATCH_EVENTS: () => MAX_BATCH_EVENTS,
   MeterFlow: () => MeterFlow,
   MeterFlowError: () => MeterFlowError,
   NotFoundError: () => NotFoundError,
+  PayloadTooLargeError: () => PayloadTooLargeError,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
   ValidationError: () => ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
+// package.json
+var version = "0.4.4";
+
 // src/errors.ts
 var MeterFlowError = class extends Error {
   errorType;
@@ -72,9 +77,18 @@ var ConflictError = class extends MeterFlowError {
   }
 };
 var ValidationError = class extends MeterFlowError {
-  constructor(message, requestId) {
+  /** Per-field detail from the API. Empty when the 422 carried none. */
+  fields;
+  constructor(message, requestId, fields = []) {
     super(message, "validation_error", false, requestId, 422);
     this.name = "ValidationError";
+    this.fields = fields;
+  }
+};
+var PayloadTooLargeError = class extends MeterFlowError {
+  constructor(message, requestId) {
+    super(message, "payload_too_large", false, requestId, 413);
+    this.name = "PayloadTooLargeError";
   }
 };
 var RateLimitError = class extends MeterFlowError {
@@ -121,7 +135,7 @@ async function retryable(fn, opts, shouldRetry = () => true) {
 }
 
 // src/utils/http.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = version;
 function buildUrl(baseUrl, path, query) {
   const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
   if (query) {
@@ -145,21 +159,35 @@ function buildHeaders(options, opts) {
   }
   return headers;
 }
+function isFieldError(value) {
+  return typeof value === "object" && value !== null && typeof value.field === "string" && typeof value.message === "string";
+}
 async function parseErrorBody(response) {
   try {
     const json = await response.json();
-    if (typeof json["detail"] === "string") return json["detail"];
-    return JSON.stringify(json);
+    const error = json["error"];
+    if (typeof error === "object" && error !== null) {
+      const body = error;
+      const fields = Array.isArray(body["fields"]) ? body["fields"].filter(isFieldError) : [];
+      if (typeof body["message"] === "string") {
+        const detail = fields.map((f) => `${f.field}: ${f.message}`).join("; ");
+        return { message: detail ? `${body["message"]}: ${detail}` : body["message"], fields };
+      }
+    }
+    if (typeof json["detail"] === "string") return { message: json["detail"], fields: [] };
+    return { message: JSON.stringify(json), fields: [] };
   } catch {
-    return response.statusText || `HTTP ${response.status}`;
+    return { message: response.statusText || `HTTP ${response.status}`, fields: [] };
   }
 }
-function mapResponseError(status, message, requestId, response) {
+function mapResponseError(status, parsed, requestId, response) {
+  const { message, fields } = parsed;
   if (status === 401 || status === 403) return new AuthError(message, requestId, status);
   if (status === 402) return new InsufficientCreditsError(message, requestId);
   if (status === 404) return new NotFoundError(message, requestId);
   if (status === 409) return new ConflictError(message, requestId);
-  if (status === 422) return new ValidationError(message, requestId);
+  if (status === 413) return new PayloadTooLargeError(message, requestId);
+  if (status === 422) return new ValidationError(message, requestId, fields);
   if (status === 429) {
     const retryAfterRaw = response.headers.get("Retry-After");
     const retryAfter = retryAfterRaw != null ? parseInt(retryAfterRaw, 10) : void 0;
@@ -181,8 +209,8 @@ async function httpRequest(options, method, path, opts) {
       const response = await options.fetch(url, fetchInit);
       const requestId = response.headers.get("x-request-id") ?? void 0;
       if (!response.ok) {
-        const message = await parseErrorBody(response);
-        throw mapResponseError(response.status, message, requestId, response);
+        const parsed = await parseErrorBody(response);
+        throw mapResponseError(response.status, parsed, requestId, response);
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return void 0;
@@ -225,6 +253,7 @@ var CreditsResource = class {
 };
 
 // src/resources/usage.ts
+var MAX_BATCH_EVENTS = 500;
 var UsageResource = class {
   constructor(client) {
     this.client = client;
@@ -235,7 +264,13 @@ var UsageResource = class {
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
     });
   }
+  /** Record up to `MAX_BATCH_EVENTS` events in one request. Larger arrays are rejected locally, never sent. */
   recordBatch(events, opts) {
+    if (events.length > MAX_BATCH_EVENTS) {
+      return Promise.reject(
+        new PayloadTooLargeError(`A batch may contain at most ${MAX_BATCH_EVENTS} events; this one has ${events.length}. Split it.`)
+      );
+    }
     return this.client.request("POST", "usage/events/batch", {
       body: { events },
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
@@ -338,9 +373,11 @@ var MeterFlow = class {
   AuthError,
   ConflictError,
   InsufficientCreditsError,
+  MAX_BATCH_EVENTS,
   MeterFlow,
   MeterFlowError,
   NotFoundError,
+  PayloadTooLargeError,
   RateLimitError,
   ServerError,
   ValidationError

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { MeterFlow } from "./client";
-export { MeterFlowError, AuthError, NotFoundError, InsufficientCreditsError, ConflictError, ValidationError, RateLimitError, ServerError, } from "./errors";
+export { MeterFlowError, AuthError, NotFoundError, InsufficientCreditsError, ConflictError, PayloadTooLargeError, ValidationError, RateLimitError, ServerError, type ValidationFieldError, } from "./errors";
+export { MAX_BATCH_EVENTS } from "./resources/usage";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAIrC,OAAO,EACL,cAAc,EACd,SAAS,EACT,aAAa,EACb,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAIrC,OAAO,EACL,cAAc,EACd,SAAS,EACT,aAAa,EACb,wBAAwB,EACxB,aAAa,EACb,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,WAAW,EACX,KAAK,oBAAoB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -23,15 +23,20 @@ __export(index_exports, {
   AuthError: () => AuthError,
   ConflictError: () => ConflictError,
   InsufficientCreditsError: () => InsufficientCreditsError,
+  MAX_BATCH_EVENTS: () => MAX_BATCH_EVENTS,
   MeterFlow: () => MeterFlow,
   MeterFlowError: () => MeterFlowError,
   NotFoundError: () => NotFoundError,
+  PayloadTooLargeError: () => PayloadTooLargeError,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
   ValidationError: () => ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 
+// package.json
+var version = "0.4.4";
+
 // src/errors.ts
 var MeterFlowError = class extends Error {
   errorType;
@@ -72,9 +77,18 @@ var ConflictError = class extends MeterFlowError {
   }
 };
 var ValidationError = class extends MeterFlowError {
-  constructor(message, requestId) {
+  /** Per-field detail from the API. Empty when the 422 carried none. */
+  fields;
+  constructor(message, requestId, fields = []) {
     super(message, "validation_error", false, requestId, 422);
     this.name = "ValidationError";
+    this.fields = fields;
+  }
+};
+var PayloadTooLargeError = class extends MeterFlowError {
+  constructor(message, requestId) {
+    super(message, "payload_too_large", false, requestId, 413);
+    this.name = "PayloadTooLargeError";
   }
 };
 var RateLimitError = class extends MeterFlowError {
@@ -121,7 +135,7 @@ async function retryable(fn, opts, shouldRetry = () => true) {
 }
 
 // src/utils/http.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = version;
 function buildUrl(baseUrl, path, query) {
   const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
   if (query) {
@@ -145,21 +159,35 @@ function buildHeaders(options, opts) {
   }
   return headers;
 }
+function isFieldError(value) {
+  return typeof value === "object" && value !== null && typeof value.field === "string" && typeof value.message === "string";
+}
 async function parseErrorBody(response) {
   try {
     const json = await response.json();
-    if (typeof json["detail"] === "string") return json["detail"];
-    return JSON.stringify(json);
+    const error = json["error"];
+    if (typeof error === "object" && error !== null) {
+      const body = error;
+      const fields = Array.isArray(body["fields"]) ? body["fields"].filter(isFieldError) : [];
+      if (typeof body["message"] === "string") {
+        const detail = fields.map((f) => `${f.field}: ${f.message}`).join("; ");
+        return { message: detail ? `${body["message"]}: ${detail}` : body["message"], fields };
+      }
+    }
+    if (typeof json["detail"] === "string") return { message: json["detail"], fields: [] };
+    return { message: JSON.stringify(json), fields: [] };
   } catch {
-    return response.statusText || `HTTP ${response.status}`;
+    return { message: response.statusText || `HTTP ${response.status}`, fields: [] };
   }
 }
-function mapResponseError(status, message, requestId, response) {
+function mapResponseError(status, parsed, requestId, response) {
+  const { message, fields } = parsed;
   if (status === 401 || status === 403) return new AuthError(message, requestId, status);
   if (status === 402) return new InsufficientCreditsError(message, requestId);
   if (status === 404) return new NotFoundError(message, requestId);
   if (status === 409) return new ConflictError(message, requestId);
-  if (status === 422) return new ValidationError(message, requestId);
+  if (status === 413) return new PayloadTooLargeError(message, requestId);
+  if (status === 422) return new ValidationError(message, requestId, fields);
   if (status === 429) {
     const retryAfterRaw = response.headers.get("Retry-After");
     const retryAfter = retryAfterRaw != null ? parseInt(retryAfterRaw, 10) : void 0;
@@ -181,8 +209,8 @@ async function httpRequest(options, method, path, opts) {
       const response = await options.fetch(url, fetchInit);
       const requestId = response.headers.get("x-request-id") ?? void 0;
       if (!response.ok) {
-        const message = await parseErrorBody(response);
-        throw mapResponseError(response.status, message, requestId, response);
+        const parsed = await parseErrorBody(response);
+        throw mapResponseError(response.status, parsed, requestId, response);
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return void 0;
@@ -225,6 +253,7 @@ var CreditsResource = class {
 };
 
 // src/resources/usage.ts
+var MAX_BATCH_EVENTS = 500;
 var UsageResource = class {
   constructor(client) {
     this.client = client;
@@ -235,7 +264,13 @@ var UsageResource = class {
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
     });
   }
+  /** Record up to `MAX_BATCH_EVENTS` events in one request. Larger arrays are rejected locally, never sent. */
   recordBatch(events, opts) {
+    if (events.length > MAX_BATCH_EVENTS) {
+      return Promise.reject(
+        new PayloadTooLargeError(`A batch may contain at most ${MAX_BATCH_EVENTS} events; this one has ${events.length}. Split it.`)
+      );
+    }
     return this.client.request("POST", "usage/events/batch", {
       body: { events },
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
@@ -338,9 +373,11 @@ var MeterFlow = class {
   AuthError,
   ConflictError,
   InsufficientCreditsError,
+  MAX_BATCH_EVENTS,
   MeterFlow,
   MeterFlowError,
   NotFoundError,
+  PayloadTooLargeError,
   RateLimitError,
   ServerError,
   ValidationError

package/dist/index.mjs

@@ -1,3 +1,6 @@
+// package.json
+var version = "0.4.4";
+
 // src/errors.ts
 var MeterFlowError = class extends Error {
   errorType;
@@ -38,9 +41,18 @@ var ConflictError = class extends MeterFlowError {
   }
 };
 var ValidationError = class extends MeterFlowError {
-  constructor(message, requestId) {
+  /** Per-field detail from the API. Empty when the 422 carried none. */
+  fields;
+  constructor(message, requestId, fields = []) {
     super(message, "validation_error", false, requestId, 422);
     this.name = "ValidationError";
+    this.fields = fields;
+  }
+};
+var PayloadTooLargeError = class extends MeterFlowError {
+  constructor(message, requestId) {
+    super(message, "payload_too_large", false, requestId, 413);
+    this.name = "PayloadTooLargeError";
   }
 };
 var RateLimitError = class extends MeterFlowError {
@@ -87,7 +99,7 @@ async function retryable(fn, opts, shouldRetry = () => true) {
 }
 
 // src/utils/http.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = version;
 function buildUrl(baseUrl, path, query) {
   const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
   if (query) {
@@ -111,21 +123,35 @@ function buildHeaders(options, opts) {
   }
   return headers;
 }
+function isFieldError(value) {
+  return typeof value === "object" && value !== null && typeof value.field === "string" && typeof value.message === "string";
+}
 async function parseErrorBody(response) {
   try {
     const json = await response.json();
-    if (typeof json["detail"] === "string") return json["detail"];
-    return JSON.stringify(json);
+    const error = json["error"];
+    if (typeof error === "object" && error !== null) {
+      const body = error;
+      const fields = Array.isArray(body["fields"]) ? body["fields"].filter(isFieldError) : [];
+      if (typeof body["message"] === "string") {
+        const detail = fields.map((f) => `${f.field}: ${f.message}`).join("; ");
+        return { message: detail ? `${body["message"]}: ${detail}` : body["message"], fields };
+      }
+    }
+    if (typeof json["detail"] === "string") return { message: json["detail"], fields: [] };
+    return { message: JSON.stringify(json), fields: [] };
   } catch {
-    return response.statusText || `HTTP ${response.status}`;
+    return { message: response.statusText || `HTTP ${response.status}`, fields: [] };
   }
 }
-function mapResponseError(status, message, requestId, response) {
+function mapResponseError(status, parsed, requestId, response) {
+  const { message, fields } = parsed;
   if (status === 401 || status === 403) return new AuthError(message, requestId, status);
   if (status === 402) return new InsufficientCreditsError(message, requestId);
   if (status === 404) return new NotFoundError(message, requestId);
   if (status === 409) return new ConflictError(message, requestId);
-  if (status === 422) return new ValidationError(message, requestId);
+  if (status === 413) return new PayloadTooLargeError(message, requestId);
+  if (status === 422) return new ValidationError(message, requestId, fields);
   if (status === 429) {
     const retryAfterRaw = response.headers.get("Retry-After");
     const retryAfter = retryAfterRaw != null ? parseInt(retryAfterRaw, 10) : void 0;
@@ -147,8 +173,8 @@ async function httpRequest(options, method, path, opts) {
       const response = await options.fetch(url, fetchInit);
       const requestId = response.headers.get("x-request-id") ?? void 0;
       if (!response.ok) {
-        const message = await parseErrorBody(response);
-        throw mapResponseError(response.status, message, requestId, response);
+        const parsed = await parseErrorBody(response);
+        throw mapResponseError(response.status, parsed, requestId, response);
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return void 0;
@@ -191,6 +217,7 @@ var CreditsResource = class {
 };
 
 // src/resources/usage.ts
+var MAX_BATCH_EVENTS = 500;
 var UsageResource = class {
   constructor(client) {
     this.client = client;
@@ -201,7 +228,13 @@ var UsageResource = class {
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
     });
   }
+  /** Record up to `MAX_BATCH_EVENTS` events in one request. Larger arrays are rejected locally, never sent. */
   recordBatch(events, opts) {
+    if (events.length > MAX_BATCH_EVENTS) {
+      return Promise.reject(
+        new PayloadTooLargeError(`A batch may contain at most ${MAX_BATCH_EVENTS} events; this one has ${events.length}. Split it.`)
+      );
+    }
     return this.client.request("POST", "usage/events/batch", {
       body: { events },
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
@@ -303,9 +336,11 @@ export {
   AuthError,
   ConflictError,
   InsufficientCreditsError,
+  MAX_BATCH_EVENTS,
   MeterFlow,
   MeterFlowError,
   NotFoundError,
+  PayloadTooLargeError,
   RateLimitError,
   ServerError,
   ValidationError

package/dist/resources/usage.d.ts

@@ -11,10 +11,19 @@ export interface SummaryQuery {
     from_?: string;
     to?: string;
 }
+/**
+ * The API refuses a batch above this with 413. The SDK checks it before sending so an oversized
+ * batch fails instantly, offline, with the same `PayloadTooLargeError` — and it does NOT split
+ * the batch for you: one call is one request with one idempotency key, and silently turning it
+ * into N requests would leave partial success indistinguishable from failure. Chunk at the call
+ * site, where you can pick a key per chunk.
+ */
+export declare const MAX_BATCH_EVENTS = 500;
 export declare class UsageResource {
     private readonly client;
     constructor(client: MeterFlow);
     record(body: UsageEventRequest, opts?: RecordOptions): Promise<UsageEventResponse>;
+    /** Record up to `MAX_BATCH_EVENTS` events in one request. Larger arrays are rejected locally, never sent. */
     recordBatch(events: UsageEventRequest[], opts?: RecordOptions): Promise<UsageEventResponse[]>;
     summary(customerId: string, query?: SummaryQuery): Promise<UsageSummaryResponse>;
 }

package/dist/resources/usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/resources/usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,iBAAiB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,mBAAmB,CAAC,CAAC;AACpE,KAAK,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,CAAC;AACtE,KAAK,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOlF,WAAW,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAO7F,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAKjF"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/resources/usage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,iBAAiB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,mBAAmB,CAAC,CAAC;AACpE,KAAK,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,CAAC;AACtE,KAAK,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOlF,6GAA6G;IAC7G,WAAW,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAY7F,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAKjF"}

package/dist/utils/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/utils/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAiElE,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,CAAC,CAAC,CAgCZ"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/utils/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAiGlE,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,CAAC,CAAC,CAgCZ"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meterflow",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Official Node.js SDK for MeterFlow — usage-based billing, credit management, and metering.",
   "license": "MIT",
   "author": "MeterFlow",