@peable.to/contracts 0.4.0 → 1.0.0

package/dist/cjs/resources/catalog/meters.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meterRoutes = exports.createBillingMeterEventParams = exports.billingMeterEventSummariesQuery = exports.listBillingMetersQuery = exports.billingMeterStatusParams = exports.updateBillingMeterParams = exports.createBillingMeterParams = exports.billingMeterEventSummarySchema = exports.billingMeterEventSchema = exports.billingMeterSchema = void 0;
+const zod_1 = require("zod");
+const envelopes_1 = require("../../common/envelopes");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const catalog_1 = require("../../vocabulary/catalog");
+/**
+ * Usage meters (`mtr_…`, ADR 0018 §7): usage events named `event_name`,
+ * attributed to a customer by `customer_mapping.event_payload_key` of their
+ * payload and measured by `value_settings.event_payload_key`. A metered price
+ * (`recurring.meter`) bills its aggregate per period, in arrears.
+ */
+exports.billingMeterSchema = (0, objects_1.defineObject)('billing.meter', 'BillingMeter', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('billing.meter'),
+    livemode: primitives_1.livemode,
+    display_name: zod_1.z.string(),
+    event_name: zod_1.z.string().describe('The `event_name` of the meter events it counts.'),
+    default_aggregation: zod_1.z
+        .object({
+        formula: zod_1.z
+            .enum(catalog_1.METER_AGGREGATIONS)
+            .describe("How a period's events combine into the quantity billed."),
+    })
+        .strict(),
+    customer_mapping: zod_1.z
+        .object({
+        type: zod_1.z.literal('by_id'),
+        event_payload_key: zod_1.z
+            .string()
+            .describe('The payload key carrying the customer (`cus_…`).'),
+    })
+        .strict(),
+    value_settings: zod_1.z
+        .object({
+        event_payload_key: zod_1.z.string().describe('The payload key carrying the value.'),
+    })
+        .strict(),
+    status: zod_1.z.enum(catalog_1.METER_STATUSES),
+    created: primitives_1.unixSeconds,
+    updated: primitives_1.unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'mtr_0193b8f2c1a87d3e9f4e',
+            object: 'billing.meter',
+            livemode: false,
+            display_name: 'API calls',
+            event_name: 'api_call',
+            default_aggregation: { formula: 'sum' },
+            customer_mapping: { type: 'by_id', event_payload_key: 'peable_customer_id' },
+            value_settings: { event_payload_key: 'value' },
+            status: 'active',
+            created: 1793750400,
+            updated: 1793750400,
+        },
+    ],
+});
+/**
+ * One usage event, `POST /v1/billing/meter_events`. `identifier` makes it
+ * idempotent: the same identifier is the same event, forever.
+ */
+exports.billingMeterEventSchema = (0, objects_1.defineObject)('billing.meter_event', 'BillingMeterEvent', zod_1.z
+    .object({
+    object: zod_1.z.literal('billing.meter_event'),
+    livemode: primitives_1.livemode,
+    identifier: zod_1.z.string(),
+    event_name: zod_1.z.string(),
+    payload: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.string())
+        .describe('The payload as received: the customer key and the value, as strings.'),
+    timestamp: primitives_1.unixSeconds,
+    created: primitives_1.unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            object: 'billing.meter_event',
+            livemode: false,
+            identifier: 'req_8f3a2c',
+            event_name: 'api_call',
+            payload: { peable_customer_id: 'cus_0193b8f2c1a87d3e9f4a', value: '25' },
+            timestamp: 1793750400,
+            created: 1793750400,
+        },
+    ],
+});
+/** A customer's aggregate over a window: `GET /v1/billing/meters/{id}/event_summaries`. */
+exports.billingMeterEventSummarySchema = (0, objects_1.defineObject)('billing.meter_event_summary', 'BillingMeterEventSummary', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('billing.meter_event_summary'),
+    livemode: primitives_1.livemode,
+    meter: zod_1.z.string().describe('The meter (`mtr_…`).'),
+    aggregated_value: zod_1.z
+        .string()
+        .describe('The aggregate, as an integer string (it can exceed a JS number).'),
+    start_time: primitives_1.unixSeconds,
+    end_time: primitives_1.unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'mtrsum_0193b8f2c1a87d3e9f4e_1793750400',
+            object: 'billing.meter_event_summary',
+            livemode: false,
+            meter: 'mtr_0193b8f2c1a87d3e9f4e',
+            aggregated_value: '1250',
+            start_time: 1793750400,
+            end_time: 1796342400,
+        },
+    ],
+});
+const payloadKey = zod_1.z.string().regex(/^[A-Za-z0-9_]{1,100}$/);
+const eventName = zod_1.z.string().regex(/^[A-Za-z0-9_.:-]{1,100}$/);
+const displayName = zod_1.z.string().min(1).max(250);
+exports.createBillingMeterParams = zod_1.z
+    .object({
+    display_name: displayName,
+    event_name: eventName,
+    default_aggregation: zod_1.z.object({ formula: zod_1.z.enum(catalog_1.METER_AGGREGATIONS) }).strict(),
+    customer_mapping: zod_1.z
+        .object({ type: zod_1.z.literal('by_id'), event_payload_key: payloadKey })
+        .strict()
+        .optional()
+        .describe("Default `{ type: 'by_id', event_payload_key: 'peable_customer_id' }`."),
+    value_settings: zod_1.z
+        .object({ event_payload_key: payloadKey })
+        .strict()
+        .optional()
+        .describe("Default `{ event_payload_key: 'value' }`."),
+})
+    .strict();
+exports.updateBillingMeterParams = zod_1.z.object({ display_name: displayName.optional() }).strict();
+/** The body of `deactivate` / `reactivate`: nothing. */
+exports.billingMeterStatusParams = zod_1.z.object({}).strict();
+exports.listBillingMetersQuery = (0, params_1.listQuery)({ status: zod_1.z.enum(catalog_1.METER_STATUSES).optional() });
+exports.billingMeterEventSummariesQuery = zod_1.z
+    .object({
+    customer: params_1.idParam.describe('The customer (`cus_…`) whose usage is aggregated.'),
+    start_time: params_1.queryUnixSeconds.describe('The window start (inclusive).'),
+    end_time: params_1.queryUnixSeconds.describe('The window end (exclusive), after `start_time`.'),
+})
+    .strict();
+exports.createBillingMeterEventParams = zod_1.z
+    .object({
+    event_name: eventName,
+    payload: zod_1.z.record(zod_1.z.string().max(100), zod_1.z.string().max(255)),
+    identifier: zod_1.z
+        .string()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('Default: a fresh one — pass your own so a retry is not counted twice.'),
+    timestamp: params_1.unixSecondsParam
+        .optional()
+        .describe('Default now. At most 35 days in the past, 5 minutes in the future.'),
+})
+    .strict();
+const id = { id: 'The meter (`mtr_…`).' };
+exports.meterRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'createBillingMeter',
+        method: 'post',
+        path: '/v1/billing/meters',
+        tag: 'Meters',
+        summary: 'Create a meter',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.createBillingMeterParams,
+        response: exports.billingMeterSchema,
+        sdk: 'billing.meters.create',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listBillingMeters',
+        method: 'get',
+        path: '/v1/billing/meters',
+        tag: 'Meters',
+        summary: 'List meters',
+        auth: 'service',
+        scope: 'payments:read',
+        query: exports.listBillingMetersQuery,
+        response: (0, envelopes_1.listOf)(exports.billingMeterSchema),
+        sdk: 'billing.meters.list',
+        expandable: 'billing.meter',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveBillingMeter',
+        method: 'get',
+        path: '/v1/billing/meters/{id}',
+        tag: 'Meters',
+        summary: 'Retrieve a meter',
+        auth: 'service',
+        scope: 'payments:read',
+        params: id,
+        query: params_1.expandOnlyQuery,
+        response: exports.billingMeterSchema,
+        sdk: 'billing.meters.retrieve',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateBillingMeter',
+        method: 'post',
+        path: '/v1/billing/meters/{id}',
+        tag: 'Meters',
+        summary: 'Update a meter',
+        description: 'Only `display_name` changes.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: id,
+        body: exports.updateBillingMeterParams,
+        response: exports.billingMeterSchema,
+        sdk: 'billing.meters.update',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'deactivateBillingMeter',
+        method: 'post',
+        path: '/v1/billing/meters/{id}/deactivate',
+        tag: 'Meters',
+        summary: 'Deactivate a meter',
+        description: 'An inactive meter accepts no events.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: id,
+        body: exports.billingMeterStatusParams,
+        response: exports.billingMeterSchema,
+        sdk: 'billing.meters.deactivate',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'reactivateBillingMeter',
+        method: 'post',
+        path: '/v1/billing/meters/{id}/reactivate',
+        tag: 'Meters',
+        summary: 'Reactivate a meter',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: id,
+        body: exports.billingMeterStatusParams,
+        response: exports.billingMeterSchema,
+        sdk: 'billing.meters.reactivate',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listBillingMeterEventSummaries',
+        method: 'get',
+        path: '/v1/billing/meters/{id}/event_summaries',
+        tag: 'Meters',
+        summary: "A customer's usage over a window",
+        description: 'One summary: the aggregate of the window `[start_time, end_time)`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: id,
+        query: exports.billingMeterEventSummariesQuery,
+        response: (0, envelopes_1.listOf)(exports.billingMeterEventSummarySchema),
+        sdk: 'billing.meters.listEventSummaries',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'createBillingMeterEvent',
+        method: 'post',
+        path: '/v1/billing/meter_events',
+        tag: 'Meters',
+        summary: 'Record a meter event',
+        description: 'The customer must be yours and the value a non-negative integer. A repeated `identifier` answers the stored event.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.createBillingMeterEventParams,
+        response: exports.billingMeterEventSchema,
+        sdk: 'billing.meterEvents.create',
+    }),
+];