@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/semantics/billing.js

@@ -1,220 +0,0 @@
-import { at, created, fail, list, newest, path, where } from "./shared.js";
-const METER = 'billing.meter';
-const meterMissing = (ctx, id) => fail(ctx, `No such meter: '${id}'`, 404, 'resource_missing');
-const objectOf = (v) => (v && typeof v === 'object' ? v : {});
-// a meter needs a display name, the event name it counts, and how it aggregates (sum or count)
-const createMeter = async (ctx) => {
-    const params = ctx.params;
-    const displayName = typeof params.display_name === 'string' ? params.display_name : '';
-    if (!displayName)
-        return fail(ctx, 'Missing required param: display_name.', 400, 'parameter_missing');
-    if (!(params.event_name ?? ''))
-        return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
-    const formula = objectOf(params.default_aggregation).formula;
-    if (typeof formula !== 'string' || !formula)
-        return fail(ctx, 'Missing required param: default_aggregation[formula] (sum or count).', 400, 'parameter_missing');
-    return ctx.reply(await created(ctx, METER, params, {
-        status: 'active', livemode: false,
-        customer_mapping: params.customer_mapping ?? { event_payload_key: 'stripe_customer_id', type: 'by_id' },
-        event_time_window: params.event_time_window ?? null,
-        value_settings: params.value_settings ?? { event_payload_key: 'value' },
-        status_transitions: { deactivated_at: null }, updated: ctx.now(),
-    }));
-};
-function activation(kind) {
-    return async (ctx) => {
-        const id = at(ctx, 'id');
-        const m = ctx.get(METER, id);
-        if (!m)
-            return meterMissing(ctx, id);
-        const refused = ctx.legal(METER, 'status', kind === 'deactivate' ? 'PostBillingMetersIdDeactivate' : 'PostBillingMetersIdReactivate', m.status, undefined, id);
-        if (refused)
-            return ctx.refuse(refused);
-        const fields = { ...(kind === 'deactivate' ? { status: 'inactive', status_transitions: { deactivated_at: ctx.now() } } : { status: 'active', status_transitions: { deactivated_at: null } }), updated: ctx.now() };
-        return ctx.reply(await ctx.write(METER, id, fields, `billing_meter.${kind}`));
-    };
-}
-// a meter event has no id of its own on Stripe (it carries an `identifier`); its object is billing.meter_event
-const reportUsage = async (ctx) => {
-    const params = ctx.params;
-    if (typeof params.event_name !== 'string' || !params.event_name)
-        return fail(ctx, 'Missing required param: event_name.', 400, 'parameter_missing');
-    const payload = objectOf(params.payload);
-    const body = await created(ctx, 'billing.meter_event', { ...params }, {
-        livemode: false, timestamp: params.timestamp !== undefined ? Math.trunc(Number(params.timestamp)) : ctx.now(),
-        identifier: payload.identifier ?? null, payload,
-    });
-    return ctx.reply({ ...body, object: 'billing.meter_event' });
-};
-// the meter's events for one customer in [start_time, end_time), aggregated by its formula
-const eventSummaries = async (ctx) => {
-    const id = at(ctx, 'id');
-    const m = ctx.get(METER, id);
-    if (!m)
-        return meterMissing(ctx, id);
-    const params = ctx.params;
-    const customer = typeof params.customer === 'string' ? params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (params.start_time === undefined)
-        return fail(ctx, 'Missing required param: start_time.', 400, 'parameter_missing');
-    if (params.end_time === undefined)
-        return fail(ctx, 'Missing required param: end_time.', 400, 'parameter_missing');
-    const startTime = Math.trunc(Number(params.start_time) || 0);
-    const endTime = Math.trunc(Number(params.end_time) || 0);
-    // "Must be aligned with minute boundaries" (start_time, end_time); "For hourly granularity, start and end times must
-    // align with hour boundaries … For daily granularity, … with UTC day boundaries (00:00 UTC)" (value_grouping_window;
-    // the served spec). Where the documentation stops and the twin decides: Stripe documents no error for it, so the
-    // twin answers a 400 naming the parameter and the boundary.
-    const window = params.value_grouping_window === 'hour' ? 3600 : params.value_grouping_window === 'day' ? 86_400 : 60;
-    const unit = window === 3600 ? 'hour' : window === 86_400 ? 'UTC day' : 'minute';
-    for (const [name, t] of [['start_time', startTime], ['end_time', endTime]]) {
-        if (t % window !== 0)
-            return fail(ctx, `Invalid ${name}: ${t} is not aligned with ${unit} boundaries.`, 400);
-    }
-    const mapKey = typeof objectOf(m.customer_mapping).event_payload_key === 'string' ? String(objectOf(m.customer_mapping).event_payload_key) : 'stripe_customer_id';
-    const valueKey = typeof objectOf(m.value_settings).event_payload_key === 'string' ? String(objectOf(m.value_settings).event_payload_key) : 'value';
-    const formula = objectOf(m.default_aggregation).formula ?? 'sum';
-    let aggregate = 0;
-    for (const ev of ctx.rowsRaw('billing.meter_event', { withDeleted: true })) {
-        if (ev.event_name !== String(m.event_name ?? ''))
-            continue;
-        const ts = Number(ev.timestamp) || 0;
-        if (ts < startTime || ts >= endTime)
-            continue;
-        const payload = objectOf(ev.payload);
-        if (String(payload[mapKey] ?? '') !== customer)
-            continue;
-        aggregate += formula === 'count' ? 1 : Number(payload[valueKey]) || 0;
-    }
-    return ctx.reply({
-        object: 'list', url: path(ctx), has_more: false,
-        data: [{ id: `mtrusg_twin_${id}_${customer}`, object: 'billing.meter_event_summary', meter: id, aggregated_value: aggregate, start_time: startTime, end_time: endTime, livemode: false }],
-    });
-};
-// ── credit grants: a customer's prepaid credit, paid or promotional, in a monetary amount ──
-const GRANT = 'billing.credit_grant';
-const grantMissing = (ctx, id) => fail(ctx, `No such credit grant: '${id}'`, 404, 'resource_missing');
-const createGrant = async (ctx) => {
-    const params = ctx.params;
-    const customer = typeof params.customer === 'string' ? params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.row('customer', customer, { withDeleted: true }))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    const category = typeof params.category === 'string' ? params.category : '';
-    if (category !== 'paid' && category !== 'promotional')
-        return fail(ctx, 'Invalid category: must be paid or promotional.', 400, 'parameter_invalid_string_enum');
-    const monetary = params.amount && typeof params.amount === 'object' ? objectOf(params.amount.monetary) : undefined;
-    if (!monetary || monetary.value === undefined || monetary.currency === undefined)
-        return fail(ctx, 'Missing required param: amount[monetary][value] and amount[monetary][currency].', 400, 'parameter_missing');
-    return ctx.reply(await created(ctx, GRANT, { customer }, {
-        category, livemode: false, name: params.name ?? null,
-        amount: { type: 'monetary', monetary: { currency: String(monetary.currency), value: Math.trunc(Number(monetary.value) || 0) } },
-        applicability_config: params.applicability_config && typeof params.applicability_config === 'object' ? params.applicability_config : { scope: { price_type: 'metered' } },
-        effective_at: params.effective_at !== undefined ? Math.trunc(Number(params.effective_at)) : ctx.now(),
-        expires_at: params.expires_at !== undefined ? Math.trunc(Number(params.expires_at)) : null,
-        priority: params.priority !== undefined ? Math.trunc(Number(params.priority)) : 50,
-        voided_at: null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, updated: ctx.now(),
-    }));
-};
-// expiring or voiding a grant stamps the instant; it no longer counts toward the balance
-function endGrant(kind) {
-    return async (ctx) => {
-        const id = at(ctx, 'id');
-        if (!ctx.get(GRANT, id))
-            return grantMissing(ctx, id);
-        return ctx.reply(await ctx.write(GRANT, id, { ...(kind === 'void' ? { voided_at: ctx.now() } : { expires_at: ctx.now() }), updated: ctx.now() }, `credit_grant.${kind}`));
-    };
-}
-// only the expiry and metadata change
-const updateGrant = async (ctx) => {
-    const id = at(ctx, 'id');
-    if (!ctx.get(GRANT, id))
-        return grantMissing(ctx, id);
-    const patch = { updated: ctx.now() };
-    if (ctx.params.expires_at !== undefined)
-        patch.expires_at = Math.trunc(Number(ctx.params.expires_at));
-    if (ctx.params.metadata !== undefined)
-        patch.metadata = ctx.params.metadata;
-    return ctx.reply(await ctx.write(GRANT, id, patch, 'credit_grant.update'));
-};
-// the customer's live (unvoided, unexpired) monetary grants, summed per currency
-const creditBalance = async (ctx) => {
-    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.row('customer', customer, { withDeleted: true }))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    const now = Number(ctx.now());
-    const byCurrency = {};
-    for (const g of ctx.rows(GRANT)) {
-        if (g.customer !== customer || g.voided_at != null)
-            continue;
-        if (typeof g.expires_at === 'number' && g.expires_at <= now)
-            continue;
-        const monetary = objectOf(objectOf(g.amount).monetary);
-        const cur = String(monetary.currency ?? 'usd');
-        byCurrency[cur] = (byCurrency[cur] ?? 0) + (Number(monetary.value) || 0);
-    }
-    const balances = Object.entries(byCurrency).map(([currency, value]) => ({
-        available_balance: { type: 'monetary', monetary: { currency, value } },
-        ledger_balance: { type: 'monetary', monetary: { currency, value } },
-    }));
-    return ctx.reply({ object: 'billing.credit_balance_summary', customer, balances, livemode: false });
-};
-// ── alerts: a usage threshold on a meter ──
-const ALERT = 'billing.alert';
-const createAlert = async (ctx) => {
-    const params = ctx.params;
-    if (params.alert_type !== 'usage_threshold')
-        return fail(ctx, 'Invalid alert_type: must be usage_threshold.', 400, 'parameter_invalid_string_enum');
-    if (typeof params.title !== 'string' || !params.title)
-        return fail(ctx, 'Missing required param: title.', 400, 'parameter_missing');
-    const ut = params.usage_threshold && typeof params.usage_threshold === 'object' ? params.usage_threshold : undefined;
-    if (!ut || ut.gte === undefined || typeof ut.meter !== 'string')
-        return fail(ctx, 'Missing required param: usage_threshold[gte] and usage_threshold[meter].', 400, 'parameter_missing');
-    // the spec requires recurrence too (one_time: the alert fires once)
-    if (ut.recurrence === undefined || ut.recurrence === '')
-        return fail(ctx, 'Missing required param: usage_threshold[recurrence].', 400, 'parameter_missing');
-    if (!ctx.get(METER, ut.meter))
-        return fail(ctx, `No such meter: '${ut.meter}'`, 400, 'resource_missing');
-    return ctx.reply(await created(ctx, ALERT, {}, {
-        alert_type: 'usage_threshold', livemode: false, status: 'active', title: params.title,
-        usage_threshold: { gte: Math.trunc(Number(ut.gte) || 0), meter: ut.meter, recurrence: String(ut.recurrence), filters: null },
-    }));
-};
-const listAlerts = async (ctx) => list(ctx, ALERT, where(ctx, newest(ctx, ALERT), {
-    alert_type: (a, v) => a.alert_type === v,
-    meter: (a, v) => objectOf(a.usage_threshold).meter === v,
-}));
-function alertMove(kind, operationId) {
-    return async (ctx) => {
-        const id = at(ctx, 'id');
-        const a = ctx.get(ALERT, id);
-        if (!a)
-            return fail(ctx, `No such alert: '${id}'`, 404, 'resource_missing');
-        const refused = ctx.legal(ALERT, 'status', operationId, a.status, undefined, id);
-        if (refused)
-            return ctx.refuse(refused);
-        const status = kind === 'activate' ? 'active' : kind === 'deactivate' ? 'inactive' : 'archived';
-        return ctx.reply(await ctx.write(ALERT, id, { status }, `billing_alert.${kind}`));
-    };
-}
-export const billing = {
-    PostBillingMeters: createMeter,
-    PostBillingMetersIdDeactivate: activation('deactivate'),
-    PostBillingMetersIdReactivate: activation('reactivate'),
-    PostBillingMeterEvents: reportUsage,
-    GetBillingMetersIdEventSummaries: eventSummaries,
-    PostBillingCreditGrants: createGrant,
-    PostBillingCreditGrantsIdExpire: endGrant('expire'),
-    PostBillingCreditGrantsIdVoid: endGrant('void'),
-    PostBillingCreditGrantsId: updateGrant,
-    GetBillingCreditBalanceSummary: creditBalance,
-    PostBillingAlerts: createAlert,
-    GetBillingAlerts: listAlerts,
-    PostBillingAlertsIdActivate: alertMove('activate', 'PostBillingAlertsIdActivate'),
-    PostBillingAlertsIdDeactivate: alertMove('deactivate', 'PostBillingAlertsIdDeactivate'),
-    PostBillingAlertsIdArchive: alertMove('archive', 'PostBillingAlertsIdArchive'),
-};

package/dist/src/semantics/connect.d.ts

@@ -1,5 +0,0 @@
-import type { Semantics } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** The platform's own account as Stripe's default has it, before anything is written to it. */
-export declare const platformAccountDefault: () => Row;
-export declare const connect: Record<string, Semantics>;