orb-billing 1.20.2 → 1.22.0

package/resources/customers/usage.js

@@ -0,0 +1,223 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Usage = void 0;
+const resource_1 = require("orb-billing/resource");
+class Usage extends resource_1.APIResource {
+    /**
+     * This endpoint is used to amend usage within a timeframe for a customer that has
+     * an active subscription.
+     *
+     * This endpoint will mark _all_ existing events within
+     * `[timeframe_start, timeframe_end)` as _ignored_ for billing purpo ses, and Orb
+     * will only use the _new_ events passed in the body of this request as the source
+     * of truth for that timeframe moving forwards. Note that a given time period can
+     * be amended any number of times, so events can be overwritten in subsequent calls
+     * to th is endpoint.
+     *
+     * This is a powerful and audit-safe mechanism to retroactively change usage data
+     * in cases where you need to:
+     *
+     * - decrease historical usage consumption because of degraded service availability
+     *   in your systems
+     * - account for gaps from your usage reporting mechanism
+     * - make point-in-time fixes for specific event records, while ret aining the
+     *   original time of usage and associated metadata. This amendment API is designed
+     *   with two explicit goals:
+     *
+     * 1. Amendments are **always audit-safe**. The amendment process will still retain
+     *    original events in the timeframe, though they will be ignored for billing
+     *    calculations. For auditing a nd data fidelity purposes, Orb never overwrites
+     *    or permanently deletes ingested usage data.
+     * 2. Amendments always preser ve data **consistency**. In other words, either an
+     *    amendment is fully processed by the system (and the new events for th e
+     *    timeframe are honored rather than the existing ones) or the amendment request
+     *    fails. To maintain this important proper ty, Orb prevents _partial event
+     *    ingestion_ on this endpoint.
+     *
+     * ## Response semantics
+     *
+     * - Either all events are ingested successfully, or all fail to ingest (returning
+     *   a `4xx` or `5xx` response code).
+     * - Any event that fails schema validation will lead to a `4xx` response. In this
+     *   case, to maintain data consistency, Orb will not ingest any events and will
+     *   also not deprecate existing events in the time period.
+     * - You can assume that the amendment is successful on receipt of a `2xx`
+     *   response.While a successful response from this endpoint indicates that the new
+     *   events have been ingested, updati ng usage totals happens asynchronously and
+     *   may be delayed by a few minutes.
+     *
+     * As emphasized above, Orb will never show an inconsistent state (e.g. in invoice
+     * previews or dashboards); either it will show the existing state (before the
+     * amend ment) or the new state (with new events in the requested timeframe).
+     *
+     * ## Sample request body
+     *
+     * ```json
+     * {
+     *   "events": [
+     *     {
+     *       "event_name": "payment_processed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     },
+     *     {
+     *       "event_name": "payment_failed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * ## Request Validation
+     *
+     * - The `timestamp` of each event reported must fall within the bounds of
+     *   `timeframe_start` and `timeframe_end`. As with ingestion, all timesta mps must
+     *   be sent in ISO8601 format with UTC timezone offset.
+     * - Orb **does not accept an `idempotency_key`** with each event in this endpoint,
+     *   since the entirety of the event list must be ingested to ensure consistency.
+     *   On retryable errors , you should retry the request in its entirety, and assume
+     *   that the amendment operation has not succeeded until receipt of a `2xx`.
+     *
+     * - Both `timeframe_start` and `timeframe_end` must be timestamps in the past.
+     *   Furthermore, Orb will genera lly validate that the `timeframe_start` and
+     *   `timeframe_end` fall within the customer's _current_ subscription billing pe
+     *   riod. However, Orb does allow amendments while in the grace period of the
+     *   previous billing period; in this instance, the timeframe can start before the
+     *   current period.
+     *
+     * ## API Limits
+     *
+     * Note that Orb does not currently enforce a hard rate- limit for API usage or a
+     * maximum request payload size. Similar to the event ingestion API, this API is
+     * architected for h igh-throughput ingestion. It is also safe to
+     * _programmatically_ call this endpoint if your system can automatically dete ct a
+     * need for historical amendment.
+     *
+     * In order to overwrite timeframes with a very large number of events, we suggest
+     * using multiple calls with small adjacent (e.g. every hour) timeframes.
+     */
+    update(id, params, options) {
+        const { timeframe_end, timeframe_start, ...body } = params;
+        return this.patch(`/customers/${id}/usage`, {
+            query: { timeframe_end, timeframe_start },
+            body,
+            ...options,
+        });
+    }
+    /**
+     * This endpoint is used to amend usage within a timeframe for a customer that has
+     * an active subscription.
+     *
+     * This endpoint will mark _all_ existing events within
+     * `[timeframe_start, timeframe_end)` as _ignored_ for billing purpo ses, and Orb
+     * will only use the _new_ events passed in the body of this request as the source
+     * of truth for that timeframe moving forwards. Note that a given time period can
+     * be amended any number of times, so events can be overwritten in subsequent calls
+     * to th is endpoint.
+     *
+     * This is a powerful and audit-safe mechanism to retroactively change usage data
+     * in cases where you need to:
+     *
+     * - decrease historical usage consumption because of degraded service availability
+     *   in your systems
+     * - account for gaps from your usage reporting mechanism
+     * - make point-in-time fixes for specific event records, while ret aining the
+     *   original time of usage and associated metadata. This amendment API is designed
+     *   with two explicit goals:
+     *
+     * 1. Amendments are **always audit-safe**. The amendment process will still retain
+     *    original events in the timeframe, though they will be ignored for billing
+     *    calculations. For auditing a nd data fidelity purposes, Orb never overwrites
+     *    or permanently deletes ingested usage data.
+     * 2. Amendments always preser ve data **consistency**. In other words, either an
+     *    amendment is fully processed by the system (and the new events for th e
+     *    timeframe are honored rather than the existing ones) or the amendment request
+     *    fails. To maintain this important proper ty, Orb prevents _partial event
+     *    ingestion_ on this endpoint.
+     *
+     * ## Response semantics
+     *
+     * - Either all events are ingested successfully, or all fail to ingest (returning
+     *   a `4xx` or `5xx` response code).
+     * - Any event that fails schema validation will lead to a `4xx` response. In this
+     *   case, to maintain data consistency, Orb will not ingest any events and will
+     *   also not deprecate existing events in the time period.
+     * - You can assume that the amendment is successful on receipt of a `2xx`
+     *   response.While a successful response from this endpoint indicates that the new
+     *   events have been ingested, updati ng usage totals happens asynchronously and
+     *   may be delayed by a few minutes.
+     *
+     * As emphasized above, Orb will never show an inconsistent state (e.g. in invoice
+     * previews or dashboards); either it will show the existing state (before the
+     * amend ment) or the new state (with new events in the requested timeframe).
+     *
+     * ## Sample request body
+     *
+     * ```json
+     * {
+     *   "events": [
+     *     {
+     *       "event_name": "payment_processed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     },
+     *     {
+     *       "event_name": "payment_failed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * ## Request Validation
+     *
+     * - The `timestamp` of each event reported must fall within the bounds of
+     *   `timeframe_start` and `timeframe_end`. As with ingestion, all timesta mps must
+     *   be sent in ISO8601 format with UTC timezone offset.
+     * - Orb **does not accept an `idempotency_key`** with each event in this endpoint,
+     *   since the entirety of the event list must be ingested to ensure consistency.
+     *   On retryable errors , you should retry the request in its entirety, and assume
+     *   that the amendment operation has not succeeded until receipt of a `2xx`.
+     *
+     * - Both `timeframe_start` and `timeframe_end` must be timestamps in the past.
+     *   Furthermore, Orb will genera lly validate that the `timeframe_start` and
+     *   `timeframe_end` fall within the customer's _current_ subscription billing pe
+     *   riod. However, Orb does allow amendments while in the grace period of the
+     *   previous billing period; in this instance, the timeframe can start before the
+     *   current period.
+     *
+     * ## API Limits
+     *
+     * Note that Orb does not currently enforce a hard rate- limit for API usage or a
+     * maximum request payload size. Similar to the event ingestion API, this API is
+     * architected for h igh-throughput ingestion. It is also safe to
+     * _programmatically_ call this endpoint if your system can automatically dete ct a
+     * need for historical amendment.
+     *
+     * In order to overwrite timeframes with a very large number of events, we suggest
+     * using multiple calls with small adjacent (e.g. every hour) timeframes.
+     */
+    updateByExternalId(id, params, options) {
+        const { timeframe_end, timeframe_start, ...body } = params;
+        return this.patch(`/customers/external_customer_id/${id}/usage`, {
+            query: { timeframe_end, timeframe_start },
+            body,
+            ...options,
+        });
+    }
+}
+exports.Usage = Usage;
+(function (Usage) {
+})(Usage = exports.Usage || (exports.Usage = {}));
+//# sourceMappingURL=usage.js.map

package/resources/customers/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/resources/customers/usage.ts"],"names":[],"mappings":";AAAA,qDAAqD;;;AAGrD,mDAAmD;AAGnD,MAAa,KAAM,SAAQ,sBAAW;IACpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiGG;IACH,MAAM,CACJ,EAAiB,EACjB,MAAyB,EACzB,OAA6B;QAE7B,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,EAAE;YAC1C,KAAK,EAAE,EAAE,aAAa,EAAE,eAAe,EAAE;YACzC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiGG;IACH,kBAAkB,CAChB,EAAiB,EACjB,MAAqC,EACrC,OAA6B;QAE7B,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,mCAAmC,EAAE,QAAQ,EAAE;YAC/D,KAAK,EAAE,EAAE,aAAa,EAAE,eAAe,EAAE;YACzC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF;AA9ND,sBA8NC;AAoHD,WAAiB,KAAK;AAKtB,CAAC,EALgB,KAAK,GAAL,aAAK,KAAL,aAAK,QAKrB"}

package/resources/customers/usage.mjs

@@ -0,0 +1,219 @@
+// File generated from our OpenAPI spec by Stainless.
+import { APIResource } from 'orb-billing/resource';
+export class Usage extends APIResource {
+    /**
+     * This endpoint is used to amend usage within a timeframe for a customer that has
+     * an active subscription.
+     *
+     * This endpoint will mark _all_ existing events within
+     * `[timeframe_start, timeframe_end)` as _ignored_ for billing purpo ses, and Orb
+     * will only use the _new_ events passed in the body of this request as the source
+     * of truth for that timeframe moving forwards. Note that a given time period can
+     * be amended any number of times, so events can be overwritten in subsequent calls
+     * to th is endpoint.
+     *
+     * This is a powerful and audit-safe mechanism to retroactively change usage data
+     * in cases where you need to:
+     *
+     * - decrease historical usage consumption because of degraded service availability
+     *   in your systems
+     * - account for gaps from your usage reporting mechanism
+     * - make point-in-time fixes for specific event records, while ret aining the
+     *   original time of usage and associated metadata. This amendment API is designed
+     *   with two explicit goals:
+     *
+     * 1. Amendments are **always audit-safe**. The amendment process will still retain
+     *    original events in the timeframe, though they will be ignored for billing
+     *    calculations. For auditing a nd data fidelity purposes, Orb never overwrites
+     *    or permanently deletes ingested usage data.
+     * 2. Amendments always preser ve data **consistency**. In other words, either an
+     *    amendment is fully processed by the system (and the new events for th e
+     *    timeframe are honored rather than the existing ones) or the amendment request
+     *    fails. To maintain this important proper ty, Orb prevents _partial event
+     *    ingestion_ on this endpoint.
+     *
+     * ## Response semantics
+     *
+     * - Either all events are ingested successfully, or all fail to ingest (returning
+     *   a `4xx` or `5xx` response code).
+     * - Any event that fails schema validation will lead to a `4xx` response. In this
+     *   case, to maintain data consistency, Orb will not ingest any events and will
+     *   also not deprecate existing events in the time period.
+     * - You can assume that the amendment is successful on receipt of a `2xx`
+     *   response.While a successful response from this endpoint indicates that the new
+     *   events have been ingested, updati ng usage totals happens asynchronously and
+     *   may be delayed by a few minutes.
+     *
+     * As emphasized above, Orb will never show an inconsistent state (e.g. in invoice
+     * previews or dashboards); either it will show the existing state (before the
+     * amend ment) or the new state (with new events in the requested timeframe).
+     *
+     * ## Sample request body
+     *
+     * ```json
+     * {
+     *   "events": [
+     *     {
+     *       "event_name": "payment_processed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     },
+     *     {
+     *       "event_name": "payment_failed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * ## Request Validation
+     *
+     * - The `timestamp` of each event reported must fall within the bounds of
+     *   `timeframe_start` and `timeframe_end`. As with ingestion, all timesta mps must
+     *   be sent in ISO8601 format with UTC timezone offset.
+     * - Orb **does not accept an `idempotency_key`** with each event in this endpoint,
+     *   since the entirety of the event list must be ingested to ensure consistency.
+     *   On retryable errors , you should retry the request in its entirety, and assume
+     *   that the amendment operation has not succeeded until receipt of a `2xx`.
+     *
+     * - Both `timeframe_start` and `timeframe_end` must be timestamps in the past.
+     *   Furthermore, Orb will genera lly validate that the `timeframe_start` and
+     *   `timeframe_end` fall within the customer's _current_ subscription billing pe
+     *   riod. However, Orb does allow amendments while in the grace period of the
+     *   previous billing period; in this instance, the timeframe can start before the
+     *   current period.
+     *
+     * ## API Limits
+     *
+     * Note that Orb does not currently enforce a hard rate- limit for API usage or a
+     * maximum request payload size. Similar to the event ingestion API, this API is
+     * architected for h igh-throughput ingestion. It is also safe to
+     * _programmatically_ call this endpoint if your system can automatically dete ct a
+     * need for historical amendment.
+     *
+     * In order to overwrite timeframes with a very large number of events, we suggest
+     * using multiple calls with small adjacent (e.g. every hour) timeframes.
+     */
+    update(id, params, options) {
+        const { timeframe_end, timeframe_start, ...body } = params;
+        return this.patch(`/customers/${id}/usage`, {
+            query: { timeframe_end, timeframe_start },
+            body,
+            ...options,
+        });
+    }
+    /**
+     * This endpoint is used to amend usage within a timeframe for a customer that has
+     * an active subscription.
+     *
+     * This endpoint will mark _all_ existing events within
+     * `[timeframe_start, timeframe_end)` as _ignored_ for billing purpo ses, and Orb
+     * will only use the _new_ events passed in the body of this request as the source
+     * of truth for that timeframe moving forwards. Note that a given time period can
+     * be amended any number of times, so events can be overwritten in subsequent calls
+     * to th is endpoint.
+     *
+     * This is a powerful and audit-safe mechanism to retroactively change usage data
+     * in cases where you need to:
+     *
+     * - decrease historical usage consumption because of degraded service availability
+     *   in your systems
+     * - account for gaps from your usage reporting mechanism
+     * - make point-in-time fixes for specific event records, while ret aining the
+     *   original time of usage and associated metadata. This amendment API is designed
+     *   with two explicit goals:
+     *
+     * 1. Amendments are **always audit-safe**. The amendment process will still retain
+     *    original events in the timeframe, though they will be ignored for billing
+     *    calculations. For auditing a nd data fidelity purposes, Orb never overwrites
+     *    or permanently deletes ingested usage data.
+     * 2. Amendments always preser ve data **consistency**. In other words, either an
+     *    amendment is fully processed by the system (and the new events for th e
+     *    timeframe are honored rather than the existing ones) or the amendment request
+     *    fails. To maintain this important proper ty, Orb prevents _partial event
+     *    ingestion_ on this endpoint.
+     *
+     * ## Response semantics
+     *
+     * - Either all events are ingested successfully, or all fail to ingest (returning
+     *   a `4xx` or `5xx` response code).
+     * - Any event that fails schema validation will lead to a `4xx` response. In this
+     *   case, to maintain data consistency, Orb will not ingest any events and will
+     *   also not deprecate existing events in the time period.
+     * - You can assume that the amendment is successful on receipt of a `2xx`
+     *   response.While a successful response from this endpoint indicates that the new
+     *   events have been ingested, updati ng usage totals happens asynchronously and
+     *   may be delayed by a few minutes.
+     *
+     * As emphasized above, Orb will never show an inconsistent state (e.g. in invoice
+     * previews or dashboards); either it will show the existing state (before the
+     * amend ment) or the new state (with new events in the requested timeframe).
+     *
+     * ## Sample request body
+     *
+     * ```json
+     * {
+     *   "events": [
+     *     {
+     *       "event_name": "payment_processed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     },
+     *     {
+     *       "event_name": "payment_failed",
+     *       "timestamp": "2022-03-24T07:15:00Z",
+     *       "properties": {
+     *         "amount": 100
+     *       }
+     *     }
+     *   ]
+     * }
+     * ```
+     *
+     * ## Request Validation
+     *
+     * - The `timestamp` of each event reported must fall within the bounds of
+     *   `timeframe_start` and `timeframe_end`. As with ingestion, all timesta mps must
+     *   be sent in ISO8601 format with UTC timezone offset.
+     * - Orb **does not accept an `idempotency_key`** with each event in this endpoint,
+     *   since the entirety of the event list must be ingested to ensure consistency.
+     *   On retryable errors , you should retry the request in its entirety, and assume
+     *   that the amendment operation has not succeeded until receipt of a `2xx`.
+     *
+     * - Both `timeframe_start` and `timeframe_end` must be timestamps in the past.
+     *   Furthermore, Orb will genera lly validate that the `timeframe_start` and
+     *   `timeframe_end` fall within the customer's _current_ subscription billing pe
+     *   riod. However, Orb does allow amendments while in the grace period of the
+     *   previous billing period; in this instance, the timeframe can start before the
+     *   current period.
+     *
+     * ## API Limits
+     *
+     * Note that Orb does not currently enforce a hard rate- limit for API usage or a
+     * maximum request payload size. Similar to the event ingestion API, this API is
+     * architected for h igh-throughput ingestion. It is also safe to
+     * _programmatically_ call this endpoint if your system can automatically dete ct a
+     * need for historical amendment.
+     *
+     * In order to overwrite timeframes with a very large number of events, we suggest
+     * using multiple calls with small adjacent (e.g. every hour) timeframes.
+     */
+    updateByExternalId(id, params, options) {
+        const { timeframe_end, timeframe_start, ...body } = params;
+        return this.patch(`/customers/external_customer_id/${id}/usage`, {
+            query: { timeframe_end, timeframe_start },
+            body,
+            ...options,
+        });
+    }
+}
+(function (Usage) {
+})(Usage || (Usage = {}));
+//# sourceMappingURL=usage.mjs.map

package/resources/customers/usage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.mjs","sourceRoot":"","sources":["../../src/resources/customers/usage.ts"],"names":[],"mappings":"AAAA,qDAAqD;OAG9C,EAAE,WAAW,EAAE,MAAM,sBAAsB;AAGlD,MAAM,OAAO,KAAM,SAAQ,WAAW;IACpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiGG;IACH,MAAM,CACJ,EAAiB,EACjB,MAAyB,EACzB,OAA6B;QAE7B,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,EAAE;YAC1C,KAAK,EAAE,EAAE,aAAa,EAAE,eAAe,EAAE;YACzC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiGG;IACH,kBAAkB,CAChB,EAAiB,EACjB,MAAqC,EACrC,OAA6B;QAE7B,MAAM,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,mCAAmC,EAAE,QAAQ,EAAE;YAC/D,KAAK,EAAE,EAAE,aAAa,EAAE,eAAe,EAAE;YACzC,IAAI;YACJ,GAAG,OAAO;SACX,CAAC,CAAC;IACL,CAAC;CACF;AAoHD,WAAiB,KAAK;AAKtB,CAAC,EALgB,KAAK,KAAL,KAAK,QAKrB"}