mbase-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,557 @@
+type MeterbaseOptions = {
+    /** A secret key. It names its own workspace. */
+    apiKey: string;
+    /** Defaults to the hosted engine. */
+    baseUrl?: string;
+    /** Per attempt, not per call. */
+    timeout?: number;
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+};
+type RequestOptions = {
+    signal?: AbortSignal;
+    timeout?: number;
+    maxRetries?: number;
+};
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+type Request = RequestOptions & {
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Replay this call even though its method is not safe. Only a route that
+     * carries an idempotency key may set it, and the key has to be fixed before
+     * `request` is called — the loop re-sends one body, so a key generated
+     * per attempt would count the same usage twice.
+     */
+    idempotent?: boolean;
+};
+declare class Client {
+    #private;
+    constructor(options: MeterbaseOptions);
+    request<T>(req: Request): Promise<T>;
+}
+
+/** Enveloped so pagination can arrive without breaking callers. */
+type List<T> = {
+    data: T[];
+};
+type Meter = {
+    id: string;
+    workspace_id: string;
+    key: string;
+    name: string;
+    description: string;
+    unit: string;
+    value: string;
+    /** Usage-alert percents for this meter. `null` inherits the workspace's
+     * defaults; `[]` turns alerts off for the meter. A customer's own list
+     * beats this one. */
+    thresholds: number[] | null;
+    created_at: string;
+    updated_at: string;
+    archived_at: string | null;
+};
+type MeterCreateParams = {
+    key: string;
+    name: string;
+    description?: string;
+    unit?: string;
+    value?: string;
+    /** Whole percents, 1–1000, at most 32 of them; a mark over 100 is an
+     * overage alert. Omitted, the meter inherits the workspace's. */
+    thresholds?: number[];
+};
+/**
+ * An omitted field is left alone; `""` clears an optional one.
+ *
+ * `thresholds` is the exception on both counts: `null` is a value there, not
+ * silence. Omit it to keep the stored list, send `null` to inherit the
+ * workspace's again, send `[]` to turn alerts off for this meter.
+ */
+type MeterUpdateParams = {
+    key?: string;
+    name?: string;
+    description?: string;
+    unit?: string;
+    value?: string;
+    thresholds?: number[] | null;
+};
+type MeterListParams = {
+    include_archived?: boolean;
+};
+type Customer = {
+    id: string;
+    workspace_id: string;
+    external_id: string;
+    name: string;
+    metadata: Record<string, unknown>;
+    /** Usage-alert percents for this customer. `null` inherits — the meter's
+     * list, then the workspace's. `[]` turns alerts off for this customer.
+     * The most specific of the three, and it always wins. */
+    thresholds: number[] | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+};
+type CustomerCreateParams = {
+    external_id: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    /** Whole percents, 1–1000, at most 32 of them; a mark over 100 is an
+     * overage alert. Omitted, the customer inherits. */
+    thresholds?: number[];
+};
+/**
+ * An omitted field is left alone. `external_id` cannot be cleared, and
+ * `metadata` is replaced wholesale rather than merged.
+ *
+ * `thresholds` reads `null` as a value, not as silence: omit it to keep the
+ * stored list, send `null` to go back to inheriting the meter's or the
+ * workspace's, send `[]` to turn alerts off for this customer alone.
+ */
+type CustomerUpdateParams = {
+    external_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    thresholds?: number[] | null;
+};
+type CustomerListParams = {
+    include_deleted?: boolean;
+};
+/** `customer_id` is the tenant's own external id and `meter_id` the meter's
+ * key: an SDK never holds Meterbase uuids. */
+type CheckParams = {
+    customer_id: string;
+    meter_id: string;
+    /** What is about to be consumed, `1 … 100000000000`. Defaults to `1`, which
+     * asks whether there is any capacity at all. */
+    quantity?: number;
+};
+type CheckResult = {
+    allowed: boolean;
+    /** Unlimited for this meter. `available` is `null`. */
+    no_cap: boolean;
+    /**
+     * The whole capacity: the plan's unused entitlement for the current period,
+     * floored at 0, plus every open grant. `null` under `no_cap`, where capacity
+     * is not a number.
+     *
+     * One figure and no breakdown: `check` answers from a single cached integer,
+     * and itemising where the capacity came from would cost it that. For the
+     * per-grant detail, read `customers.allowances.list`.
+     */
+    available: number | null;
+};
+/**
+ * `track` records work that already happened, so it never refuses on capacity
+ * — the gate is `check`, which runs before the work. A quantity beyond the
+ * customer's capacity is recorded, drives `available` to 0, and the next
+ * `check` says no.
+ */
+type TrackParams = {
+    customer_id: string;
+    meter_id: string;
+    /** Integer, `1 … 100000000000`. Defaults to `1`, which is what a counting
+     * meter sends. */
+    quantity?: number;
+    /**
+     * RFC 3339, defaulting to now, and it must fall inside the workspace's
+     * window — by default 7 days back and 5 minutes ahead. Keeping it apart
+     * from `recorded_at` is what lets usage be reported late.
+     */
+    occurred_at?: string;
+    /**
+     * The engine requires one; the SDK generates one per call when it is
+     * omitted, and reuses it across that call's retries. Supply your own when
+     * the caller already has an id for the work — a job id, a request id — so a
+     * retry from further out replays rather than counts twice.
+     */
+    idempotency_key?: string;
+};
+/** Enveloped, like the list reads, so the receipt can grow a sibling field
+ * without breaking callers. */
+type TrackResult = {
+    event: UsageEvent;
+};
+/**
+ * A receipt. The same shape whether the event is new, a replay, or dated
+ * inside a period that has already closed — no capacity figures, no nullable
+ * fields, nothing to branch on.
+ */
+type UsageEvent = {
+    /** Meterbase's id for the event. A retry of the same key returns this same
+     * id. */
+    id: string;
+    customer_id: string;
+    meter_id: string;
+    quantity: number;
+    /** As supplied, or now. Chooses the period the event counts against. */
+    occurred_at: string;
+    /** When Meterbase stored it, which is not `occurred_at`. */
+    recorded_at: string;
+    idempotency_key: string;
+    /** `true` when this key had already been recorded: nothing was written, and
+     * this is the original event. */
+    replayed: boolean;
+};
+/**
+ * A plan's billing period. Every recurring allowance it holds is measured
+ * against it, and it is fixed when the plan is created. `one_time` is not
+ * among them: that is a kind of allowance, not a period.
+ */
+type PlanCycle = "daily" | "weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly";
+type Plan = {
+    id: string;
+    workspace_id: string;
+    key: string;
+    name: string;
+    description: string;
+    cycle: PlanCycle;
+    created_at: string;
+    updated_at: string;
+    archived_at: string | null;
+};
+type PlanCreateParams = {
+    key: string;
+    name: string;
+    description?: string;
+    cycle: PlanCycle;
+};
+/**
+ * An omitted field is left alone; `""` clears the description. There is no
+ * `cycle`: moving a plan's period would re-date every period its customers
+ * were already measured against, so a different cadence is a different plan.
+ */
+type PlanUpdateParams = {
+    key?: string;
+    name?: string;
+    description?: string;
+};
+type PlanListParams = {
+    include_archived?: boolean;
+};
+/**
+ * Which of a `(plan, meter)` pair's two lineages a version belongs to. Each
+ * numbers itself separately.
+ */
+type PlanAllowanceKind = "recurring" | "one_time";
+type ApplyMode = "immediate" | "next_cycle";
+type Reconciliation = "none" | "prorate" | "rebalance";
+/**
+ * How long a one-time grant lives once minted. Months are kept apart from
+ * days because they are not the same length: three months from Jan 31 dies
+ * Apr 30, ninety days dies May 1.
+ */
+type Validity = {
+    months: number;
+    days: number;
+};
+type PlanAllowance = {
+    id: string;
+    workspace_id: string;
+    plan_id: string;
+    meter_id: string;
+    /** 1, 2, 3… per lineage. Assigned by the engine, never by the caller. */
+    version: number;
+    /** Units per period. `0` is legal and grants nothing. `null` under no_cap. */
+    amount: number | null;
+    no_cap: boolean;
+    kind: PlanAllowanceKind;
+    /** `one_time` only; `null` is a grant that never expires. */
+    valid_for: Validity | null;
+    effective_from: string;
+    apply_mode: ApplyMode;
+    reconciliation: Reconciliation;
+    created_at: string;
+};
+/**
+ * An allowance says how much, never how often: the period is the plan's
+ * cycle. Give exactly one of `amount` or `no_cap`.
+ */
+type PlanAllowanceSetParams = {
+    meter_id: string;
+    amount?: number;
+    no_cap?: boolean;
+    /** Defaults to `recurring`. */
+    kind?: PlanAllowanceKind;
+    /** `one_time` only. */
+    valid_for?: Validity;
+    /** Defaults to `next_cycle`, except `one_time` which is always immediate. */
+    apply_mode?: ApplyMode;
+    /** `immediate` only. Defaults to `none`. */
+    reconciliation?: Reconciliation;
+};
+type PlanAllowanceListParams = {
+    meter_id?: string;
+};
+type Assignment = {
+    id: string;
+    workspace_id: string;
+    customer_id: string;
+    plan_id: string;
+    /** Ahead of now for a change that has not landed yet. */
+    effective_at: string;
+    /** As recorded, which is not always as asked: a first plan starts at once. */
+    effective: ApplyMode;
+    reconciliation: Reconciliation | "reset";
+    /** What periods are measured from. A plan change inherits it, so a
+     * customer's renewal day never moves under them. */
+    anchor_at: string;
+    /** Set when a newer instruction replaced this one before it took effect. */
+    superseded_at: string | null;
+    created_at: string;
+};
+/** Assigning and changing are one operation: the history is append-only. */
+type AssignPlanParams = {
+    plan_id: string;
+    /** Defaults to `next_cycle` on a change, and is forced to `immediate` on a
+     * customer's first plan: there is no period to wait out. */
+    effective?: ApplyMode;
+    reconciliation?: Reconciliation | "reset";
+    /** The customer's first assignment only, and the one chance to stagger
+     * their billing day. Defaults to the instant it lands. */
+    cycle_anchor?: string;
+};
+/** `plan` is not accepted on a grant: the engine mints those itself when a
+ * plan is assigned. */
+type AllowanceSource = "purchased" | "bonus" | "manual";
+type Allowance = {
+    id: string;
+    workspace_id: string;
+    customer_id: string;
+    meter_id: string;
+    amount: number | null;
+    no_cap: boolean;
+    consumed: number;
+    /** `null` under no_cap. */
+    remaining: number | null;
+    source: AllowanceSource | "plan";
+    metadata: Record<string, unknown>;
+    effective_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+    exhausted_at: string | null;
+    created_at: string;
+    /** Null unless `source` is `plan`. Together they answer where the grant
+     * came from and why it went away. */
+    plan_allowance_version_id: string | null;
+    assignment_id: string | null;
+    cancelled_at: string | null;
+};
+/** Give exactly one of `amount` or `no_cap`. Unlike a plan allowance, a grant
+ * of 0 is refused: a grant that gives nothing is a no-op, not a state. */
+type AllowanceGrantParams = {
+    meter_id: string;
+    /** At least 1. */
+    amount?: number;
+    no_cap?: boolean;
+    /** Required: the engine will not guess why capacity was handed out. */
+    source: AllowanceSource;
+    metadata?: Record<string, unknown>;
+    /** Defaults to now. Dated ahead, the grant is inert until then. */
+    effective_at?: string;
+    expires_at?: string;
+};
+type AllowanceListParams = {
+    meter_id?: string;
+    /** Revoked, expired and exhausted grants as well as open ones. */
+    include_closed?: boolean;
+};
+type WhoAmI = {
+    workspace: string;
+    caller: string;
+    kind: "api_key" | "service";
+};
+
+/**
+ * Capacity handed to one customer on top of their plan. A grant with
+ * `source: "plan"` is the engine's own, minted when a plan is assigned, and
+ * cannot be created here.
+ */
+declare class CustomerAllowances {
+    #private;
+    constructor(client: Client);
+    grant(customerId: string, params: AllowanceGrantParams, options?: RequestOptions): Promise<Allowance>;
+    /** Open grants only, unless `include_closed`. */
+    list(customerId: string, params?: AllowanceListParams, options?: RequestOptions): Promise<List<Allowance>>;
+    retrieve(customerId: string, allowanceId: string, options?: RequestOptions): Promise<Allowance>;
+    /** Withdraws what is left without erasing what was consumed. Idempotent. */
+    revoke(customerId: string, allowanceId: string, options?: RequestOptions): Promise<Allowance>;
+}
+
+/**
+ * Which plan a customer holds. The history is append-only: there is no patch
+ * and no delete, and assigning a plan to a customer who already has one is
+ * the same call as their first.
+ */
+declare class CustomerPlan {
+    #private;
+    constructor(client: Client);
+    /** Returns the instruction as recorded, which is where to read when it lands. */
+    assign(customerId: string, params: AssignPlanParams, options?: RequestOptions): Promise<Assignment>;
+    /**
+     * The plan in force now, which is not always the newest instruction: a
+     * change dated ahead does not govern yet. Throws NotFoundError when the
+     * customer holds no plan.
+     */
+    retrieve(customerId: string, options?: RequestOptions): Promise<Assignment>;
+    /** Every instruction, superseded ones included: it is the whole trail. */
+    history(customerId: string, options?: RequestOptions): Promise<List<Assignment>>;
+}
+
+declare class Customers {
+    #private;
+    /** The plan they hold, and the trail of instructions that got them there. */
+    readonly plan: CustomerPlan;
+    /** Grants, which sit on top of whatever the plan gives. */
+    readonly allowances: CustomerAllowances;
+    constructor(client: Client);
+    create(params: CustomerCreateParams, options?: RequestOptions): Promise<Customer>;
+    list(params?: CustomerListParams, options?: RequestOptions): Promise<List<Customer>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Customer>;
+    /**
+     * Resolves the tenant's own identifier, or null. The engine answers this as
+     * a filtered list, so a miss is an empty collection rather than a 404.
+     */
+    retrieveByExternalId(externalId: string, options?: RequestOptions): Promise<Customer | null>;
+    update(id: string, params: CustomerUpdateParams, options?: RequestOptions): Promise<Customer>;
+    /** Soft delete: usage and assignments keep referencing the customer. */
+    delete(id: string, options?: RequestOptions): Promise<Customer>;
+}
+
+declare class Meters {
+    #private;
+    constructor(client: Client);
+    create(params: MeterCreateParams, options?: RequestOptions): Promise<Meter>;
+    list(params?: MeterListParams, options?: RequestOptions): Promise<List<Meter>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Meter>;
+    update(id: string, params: MeterUpdateParams, options?: RequestOptions): Promise<Meter>;
+    /** Soft delete: plans and usage keep referencing the meter. Idempotent. */
+    archive(id: string, options?: RequestOptions): Promise<Meter>;
+}
+
+/**
+ * A plan's entitlement, versioned. There is no update and no delete: an edit
+ * appends the next version, so which amount applied when stays derivable.
+ */
+declare class PlanAllowances {
+    #private;
+    constructor(client: Client);
+    set(planId: string, params: PlanAllowanceSetParams, options?: RequestOptions): Promise<PlanAllowance>;
+    /** Every version of every meter, newest first — history, not just current. */
+    list(planId: string, params?: PlanAllowanceListParams, options?: RequestOptions): Promise<List<PlanAllowance>>;
+}
+declare class Plans {
+    #private;
+    readonly allowances: PlanAllowances;
+    constructor(client: Client);
+    /** A new plan grants nothing; attach entitlement with `allowances.set`. */
+    create(params: PlanCreateParams, options?: RequestOptions): Promise<Plan>;
+    list(params?: PlanListParams, options?: RequestOptions): Promise<List<Plan>>;
+    retrieve(id: string, options?: RequestOptions): Promise<Plan>;
+    update(id: string, params: PlanUpdateParams, options?: RequestOptions): Promise<Plan>;
+    /**
+     * Stops new assignments without withdrawing capacity from anyone already on
+     * the plan, which is why an archived plan still resolves by id. Idempotent.
+     */
+    archive(id: string, options?: RequestOptions): Promise<Plan>;
+}
+
+declare class MeterbaseError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class APIError extends MeterbaseError {
+    readonly status: number;
+    readonly code: string;
+    /** From `X-Request-Id`, when the engine sends one. */
+    readonly requestId: string | undefined;
+    readonly body: unknown;
+    constructor(args: {
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string | undefined;
+        body?: unknown;
+    });
+}
+declare class AuthenticationError extends APIError {
+}
+declare class PermissionDeniedError extends APIError {
+}
+declare class NotFoundError extends APIError {
+}
+declare class ConflictError extends APIError {
+}
+/**
+ * `409 idempotency_conflict`: the key is in use for a different meter or
+ * quantity. A caller told their key is taken asks what it recorded next, so
+ * the engine names the original and this carries it.
+ *
+ * A `ConflictError` still, so `catch (e) { if (e instanceof ConflictError) }`
+ * keeps working.
+ */
+declare class IdempotencyConflictError extends ConflictError {
+    /** The event that key already recorded. Undefined only if the engine sent a
+     * body this could not be read out of. */
+    readonly existingEventId: string | undefined;
+    constructor(args: ConstructorParameters<typeof APIError>[0]);
+}
+declare class InvalidRequestError extends APIError {
+}
+declare class RateLimitError extends APIError {
+    /** Seconds to wait, from `Retry-After`, when the engine sends one. */
+    readonly retryAfter: number | undefined;
+    constructor(args: ConstructorParameters<typeof APIError>[0] & {
+        retryAfter?: number | undefined;
+    });
+}
+declare class ServerError extends APIError {
+}
+declare class ConnectionError extends MeterbaseError {
+}
+declare class TimeoutError extends ConnectionError {
+}
+declare function errorFromResponse(args: {
+    status: number;
+    code: string;
+    message: string;
+    requestId?: string | undefined;
+    retryAfter?: number | undefined;
+    body?: unknown;
+}): APIError;
+
+declare class Meterbase {
+    #private;
+    readonly customers: Customers;
+    readonly meters: Meters;
+    readonly plans: Plans;
+    constructor(options: MeterbaseOptions);
+    /**
+     * Asks whether a customer may consume `quantity` of a meter, named by the
+     * tenant's own external id and the meter's key. Absence of entitlement is
+     * not permission: a customer with no plan and no grant is denied.
+     *
+     * This is the gate, and the only call that ever refuses. Run it before the
+     * work; record the work with `track` afterwards.
+     */
+    check(params: CheckParams, options?: RequestOptions): Promise<CheckResult>;
+    /**
+     * Records usage that already happened — the tokens were spent, the image
+     * was generated — so it never refuses on capacity. A quantity beyond the
+     * customer's capacity is recorded, drives `available` to 0, and the next
+     * `check` says no. The answer is a receipt, not a verdict.
+     *
+     * `idempotency_key` is generated when omitted, so retrying this call — the
+     * SDK's own retries included — replays the original rather than counting
+     * the same work twice.
+     */
+    track(params: TrackParams, options?: RequestOptions): Promise<TrackResult>;
+    /** Reports which workspace this key acts for. */
+    whoami(options?: RequestOptions): Promise<WhoAmI>;
+}
+
+export { APIError, type Allowance, type AllowanceGrantParams, type AllowanceListParams, type AllowanceSource, type ApplyMode, type AssignPlanParams, type Assignment, AuthenticationError, type CheckParams, type CheckResult, ConflictError, ConnectionError, type Customer, CustomerAllowances, type CustomerCreateParams, type CustomerListParams, CustomerPlan, type CustomerUpdateParams, Customers, IdempotencyConflictError, InvalidRequestError, type List, type Meter, type MeterCreateParams, type MeterListParams, type MeterUpdateParams, Meterbase, MeterbaseError, type MeterbaseOptions, Meters, NotFoundError, PermissionDeniedError, type Plan, type PlanAllowance, type PlanAllowanceKind, type PlanAllowanceListParams, type PlanAllowanceSetParams, PlanAllowances, type PlanCreateParams, type PlanCycle, type PlanListParams, type PlanUpdateParams, Plans, RateLimitError, type Reconciliation, type RequestOptions, ServerError, TimeoutError, type TrackParams, type TrackResult, type UsageEvent, type Validity, type WhoAmI, errorFromResponse };