@happyvertical/smrt-subscriptions 0.51.21 → 0.51.24

package/dist/services/reseller.d.ts

@@ -0,0 +1,154 @@
+import { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { PricingRule, PricingStrategy, SpendingBasis, SpendingPeriod, SpendingPolicy, SpendingPolicyBehavior } from '../models/commercial.js';
+import { CreditGrant } from '../models/reseller.js';
+import { SubscriberKind } from '../types.js';
+import { BillingRelationshipReader } from './commercial.js';
+export type ResellerBillingAction = 'define_prices' | 'assign_wholesale_price_book' | 'assign_retail_price_book' | 'manage_child_spending';
+export interface ResellerBillingServiceOptions extends SmrtClassOptions {
+    /** The released smrt-tenancy billing relationship reader. */
+    billingRelationships: BillingRelationshipReader;
+    /**
+     * Optional host permission check. Without it, only a system context or a
+     * super-admin bypass may mutate reseller billing records, mirroring
+     * `BillingRelationshipService`. Once it (or the context) authorizes a call,
+     * the service performs that call's writes in a system context, because
+     * they span tenants (a parent writes rows owned by its child).
+     */
+    authorize?: (request: {
+        action: ResellerBillingAction;
+        /**
+         * The tenant whose authority the action exercises: the book's seller for
+         * `define_prices` and `assign_wholesale_price_book`, the parent for
+         * `assign_retail_price_book` and `manage_child_spending`.
+         */
+        tenantId: string;
+        childTenantId?: string;
+        /**
+         * For price-book assignments and child spending: the child's current
+         * reseller, which pays the wholesale leg. A host must confirm the caller
+         * holds `tenantId`'s authority and, for `assign_wholesale_price_book`,
+         * that the publisher is a legitimate provider for this reseller — the
+         * package can refuse only a payer-published book.
+         */
+        resellerTenantId?: string;
+    }) => Promise<boolean>;
+}
+export interface DefinePriceBookPriceInput {
+    priceBookId: string;
+    ruleKey: string;
+    metricKey: string;
+    serviceKey?: string;
+    strategy: PricingStrategy;
+    effectiveFrom?: Date;
+    effectiveTo?: Date | null;
+    priority?: number;
+    /**
+     * One entry per currency. Terms use the same *minor units per unit of usage*
+     * convention as any `PricingRule` (#2401).
+     */
+    prices: Array<{
+        currency: string;
+        terms: Record<string, unknown>;
+    }>;
+}
+export interface PriceBookLeg {
+    priceBookId: string;
+    /** Currency the leg is charged in; the book needs a price in it. */
+    currency: string;
+}
+export interface AssignPriceBooksInput {
+    childTenantId: string;
+    /** `undefined` keeps the current leg; `null` clears it. */
+    wholesale?: PriceBookLeg | null;
+    retail?: PriceBookLeg | null;
+}
+export interface PriceBookAssignmentView {
+    childTenantId: string;
+    resellerTenantId: string;
+    wholesale: PriceBookLeg | null;
+    retail: PriceBookLeg | null;
+}
+export interface DelegatedSpendingPolicyInput {
+    parentTenantId: string;
+    childTenantId: string;
+    name: string;
+    basis: SpendingBasis;
+    currency: string;
+    behavior: SpendingPolicyBehavior;
+    period?: SpendingPeriod;
+    rollingSeconds?: number;
+    /** Integer minor units; must be 0 (the default) for a `balance` policy. */
+    limitAmount?: number;
+    metricKey?: string;
+    serviceKey?: string;
+    projectId?: string;
+    subscriberKind?: SubscriberKind | '';
+    subscriberExternalId?: string;
+    priority?: number;
+    active?: boolean;
+    balanceFrom?: Date;
+}
+export interface GrantChildCreditInput {
+    parentTenantId: string;
+    childTenantId: string;
+    spendingPolicyId: string;
+    /** Signed, nonzero integer minor units of the policy currency. */
+    amount: number;
+    reason?: string;
+    source?: string;
+    sourceId?: string;
+}
+/**
+ * Manages price books, their per-relationship assignment, and the spending
+ * policies and credits a parent tenant sets on its children.
+ */
+export declare class ResellerBillingService {
+    private readonly options;
+    private readonly books;
+    private readonly assignments;
+    private readonly rules;
+    private readonly policies;
+    private readonly evaluator;
+    private constructor();
+    static create(options: ResellerBillingServiceOptions): Promise<ResellerBillingService>;
+    /**
+     * Publish one price in a book, in one or more currencies. Each currency is
+     * a `PricingRule` owned by the book's seller; re-defining the same rule key,
+     * currency, and effective date replaces that rule's terms.
+     */
+    definePrice(input: DefinePriceBookPriceInput): Promise<PricingRule[]>;
+    /**
+     * Select the wholesale and/or retail book that rates a child's usage under
+     * its current reseller relationship. The retail book must be published by
+     * that reseller; the wholesale book must be published by someone other
+     * than the reseller or child it charges. Each leg is authorized separately:
+     * the wholesale leg by its publisher (`assign_wholesale_price_book`), the
+     * retail leg by the reseller (`assign_retail_price_book`).
+     */
+    assignPriceBooks(input: AssignPriceBooksInput): Promise<PriceBookAssignmentView>;
+    /** The child's assignment under its current reseller, if any. */
+    getPriceBookAssignment(childTenantId: string): Promise<PriceBookAssignmentView | null>;
+    /**
+     * Create or replace a spending policy that a parent sets on its child. The
+     * row belongs to the child (so the ordinary evaluator enforces it for the
+     * child) and records the parent in `setByTenantId`, which locks it against
+     * changes by the child. A delegated limit left by a former parent may be
+     * replaced (not a former parent's prepaid balance, which keeps its credit
+     * ledger); one the child set for itself may not. Use `period: 'balance'`
+     * for a prepaid credit balance and fund it with {@link grantChildCredit}.
+     */
+    setDelegatedSpendingPolicy(input: DelegatedSpendingPolicyInput): Promise<SpendingPolicy>;
+    /** Credit a prepaid balance policy the parent set on its child. */
+    grantChildCredit(input: GrantChildCreditInput): Promise<CreditGrant>;
+    private requireRelationship;
+    private requireChildOf;
+    /**
+     * Read a book's metadata to learn its publisher and kind before deciding
+     * authorization. Books belong to their seller, so the read is not scoped to
+     * the caller; nothing beyond a validation error is returned on denial.
+     */
+    private readBook;
+    private requireLeg;
+    private assertManage;
+}
+//# sourceMappingURL=reseller.d.ts.map

package/dist/services/reseller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reseller.d.ts","sourceRoot":"","sources":["../../src/services/reseller.ts"],"names":[],"mappings":"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"}