@optizio/merchant-identity 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -3,9 +3,10 @@
  *
  * Consumed by:
  *  - the `merchant-identity` service Worker, which implements `IdentityClient`
- *    against the shared D1, and
+ *    and `RevenueClient` against the shared D1, and
  *  - portfolio apps (DiscountKit, CodeBulk, Stackable), which call the service
- *    over an RPC service binding through the `identity()` seam below.
+ *    over an RPC service binding through the `identity()` / `revenue()` seams
+ *    below.
  *
  * This package holds only types + pure helpers, so it has no Cloudflare or
  * runtime dependencies and is safe to import anywhere.
@@ -177,3 +178,297 @@ export declare const NOOP_IDENTITY: IdentityClient;
  * any call sites.
  */
 export declare function identity(binding: IdentityClient | null | undefined, disabled?: boolean | string): IdentityClient;
+/**
+ * Every amount below is an integer in the currency's minor units (cents for
+ * USD), never a float, and is quoted in the service's report currency
+ * (`REVENUE_REPORT_CURRENCY`, USD by default). Amounts the Partner API reported
+ * in another currency are stored raw but excluded from these aggregates and
+ * counted in the sync status, so a non-zero `skippedCurrencyRows` means the
+ * numbers below are understating the portfolio.
+ */
+export declare const MINOR_UNIT_SCALE = 2;
+/**
+ * Render minor units as a plain decimal string (`123456` -> `"1234.56"`).
+ * String math throughout: passing these through a float would round-trip
+ * large amounts inexactly, and the point of minor units is exactness.
+ */
+export declare function minorUnitsToDecimal(minor: number, scale?: number): string;
+/** `app_gid` sentinel for the portfolio-wide rollup row. */
+export declare const PORTFOLIO_APP_GID = "*";
+export type ChargeStatus = 'active' | 'frozen' | 'canceled' | 'declined' | 'expired';
+/** How a charge's amount is normalised into MRR. */
+export type BillingInterval = 'MONTHLY' | 'ANNUAL';
+export type MovementType = 'new' | 'expansion' | 'contraction' | 'churn' | 'reactivation' | 'frozen' | 'unfrozen';
+export declare const MOVEMENT_TYPES: readonly MovementType[];
+export type TrialOutcome = 'trialing' | 'converted' | 'canceled' | 'expired' | 'declined' | 'uninstalled';
+/** The three Partner API feeds the sync engine polls. */
+export type SyncFeed = 'transactions' | 'app_events' | 'account_events' | 'subscriptions';
+export type SyncMode = 'backfill' | 'incremental';
+export interface RevenueCharge {
+    chargeGid: string;
+    appGid: string;
+    /** Shopify client_id of the app, i.e. `merchant_apps.app_id`. */
+    apiKey: string | null;
+    appName: string | null;
+    shopKey: string;
+    shopDomain: string | null;
+    status: ChargeStatus;
+    amountMinor: number;
+    currencyCode: string | null;
+    interval: BillingInterval;
+    /** Monthly-normalised list price: what the plan costs before any discount. */
+    grossMrrMinor: number;
+    /** Monthly-normalised discount taken off `grossMrrMinor`. Never negative. */
+    discountMinor: number;
+    /** When the discount runs out; null for one that never does, or no discount. */
+    discountExpiresAt: string | null;
+    /**
+     * Monthly-normalised **net of discount**: what the shop is actually billed.
+     * `grossMrrMinor - discountMinor`, and 0 alongside a 0 gross while the charge is
+     * trialing. A frozen charge keeps its MRR — Shopify resumes billing at the same
+     * price when the store settles up.
+     */
+    mrrMinor: number;
+    /** The shop has asked to cancel at the end of the current cycle. */
+    cancelAtEndOfCycle: boolean;
+    /**
+     * When this charge's terms were last read from the live subscription. Null means
+     * they are still only what the event history implied, so a discount on this
+     * charge would not be reflected yet.
+     */
+    reconciledAt: string | null;
+    planName: string | null;
+    planHandle: string | null;
+    billingOn: string | null;
+    isTrial: boolean;
+    firstActivatedAt: string | null;
+    lastEventAt: string | null;
+    terminatedAt: string | null;
+    firstPaidAt: string | null;
+    lastPaidAt: string | null;
+    paidSaleCount: number;
+}
+/** Everything the support viewer needs about one store's billing. */
+export interface MerchantRevenueSummary {
+    shopDomain: string;
+    shopKey: string;
+    /** Report currency the minor-unit amounts are quoted in. */
+    currencyCode: string;
+    /** Sum of `mrrMinor` (net of discounts) across active, non-trialing charges. */
+    mrrMinor: number;
+    /** The same sum before discounts, i.e. at list price. */
+    grossMrrMinor: number;
+    /** `grossMrrMinor - mrrMinor`: what discounts take off this store's bill. */
+    discountMinor: number;
+    charges: RevenueCharge[];
+    lifetimeGrossMinor: number;
+    lifetimeNetMinor: number;
+    firstPaidAt: string | null;
+    lastPaidAt: string | null;
+    activeTrials: number;
+    /** Null when the store has no derived rows yet (never billed, or unsynced). */
+    computedAt: string | null;
+}
+/** One UTC day of the derived series: stock metrics at end of day, flows for the day. */
+export interface MrrSeriesPoint {
+    date: string;
+    /** Net of discounts: `grossMrrMinor - discountMinor`. */
+    mrrMinor: number;
+    /** List price of everything billing that day, before discounts. */
+    grossMrrMinor: number;
+    discountMinor: number;
+    /** The part of `discountMinor` that has an end date or cycles remaining. */
+    expiringDiscountMinor: number;
+    subscriptionMrrMinor: number;
+    usageMrrMinor: number;
+    activeSubscriptions: number;
+    activeTrials: number;
+    payingMerchants: number;
+    activeInstalls: number;
+    newMinor: number;
+    expansionMinor: number;
+    contractionMinor: number;
+    churnMinor: number;
+    reactivationMinor: number;
+    installs: number;
+    uninstalls: number;
+    trialsStarted: number;
+    trialsConverted: number;
+    trialsLost: number;
+    grossMinor: number;
+    netMinor: number;
+}
+export interface MovementBreakdown {
+    from: string;
+    to: string;
+    appGid: string;
+    openingMrrMinor: number;
+    closingMrrMinor: number;
+    newMinor: number;
+    expansionMinor: number;
+    contractionMinor: number;
+    churnMinor: number;
+    reactivationMinor: number;
+    /** Signed sum of the components; equals closing - opening subscription MRR. */
+    netMinor: number;
+    counts: Record<MovementType, number>;
+}
+export interface TrialFunnelCohort {
+    /** `YYYY-MM` of the trial start. */
+    cohort: string;
+    trialsStarted: number;
+    converted: number;
+    canceled: number;
+    expired: number;
+    declined: number;
+    uninstalled: number;
+    stillTrialing: number;
+    /** `converted / trialsStarted`, 0 when the cohort is empty. */
+    conversionRate: number;
+    convertedMrrMinor: number;
+}
+export interface SyncFeedStatus {
+    feed: SyncFeed;
+    scope: string;
+    mode: SyncMode;
+    windowStart: string | null;
+    windowEnd: string | null;
+    watermarkAt: string | null;
+    /**
+     * The feed has read everything there is. For the `subscriptions` recheck, which has
+     * no history to walk, it means nothing was stale when it last looked — so it dips
+     * back to false while a backlog drains, and the coordinator reads it to know there
+     * is a pass to come back for.
+     */
+    backfillComplete: boolean;
+    pagesTotal: number;
+    rowsTotal: number;
+    lastRunAt: string | null;
+    lastSuccessAt: string | null;
+    lastError: string | null;
+    lastErrorAt: string | null;
+    consecutiveFailures: number;
+}
+export interface ReplayAppStatus {
+    appGid: string;
+    appName: string | null;
+    apiKey: string | null;
+    dirty: boolean;
+    lastReplayAt: string | null;
+    lastReplayMs: number | null;
+    eventsReplayed: number | null;
+    throughAt: string | null;
+    skippedCurrencyRows: number;
+    lastError: string | null;
+}
+/** How current the live-subscription reconciliation is. */
+export interface SubscriptionReconciliationStatus {
+    /** (app, shop) pairs whose live subscription has been read at least once. */
+    checkedPairs: number;
+    /**
+     * Pairs the recheck owes a read: past the recheck interval, or never read at all.
+     *
+     * Counted over the pairs it will actually revisit — an active or frozen charge, or
+     * recent subscription activity with the app still installed — rather than over
+     * stored rows, so it is not bounded by `checkedPairs`. A pair that leaves that set
+     * keeps the timestamp of its last read and can never be refreshed, so counting it
+     * would hold this above 0 for good. Reaches 0 when the pass is caught up, which
+     * makes it the figure to alert on.
+     */
+    stalePairs: number;
+    /** Pairs the API reports as having no live subscription. */
+    absentSubscriptions: number;
+    /**
+     * Pairs we could not ask about, because the feeds have never given us a shop GID
+     * and `activeSubscription` takes one. Held apart from `absentSubscriptions` so a
+     * shop we cannot identify is never read as a cancellation; the GID is recovered
+     * from any feed that carries it, so this should be 0 and is worth an alert when
+     * it is not.
+     */
+    unresolvedPairs: number;
+    /**
+     * Live subscriptions whose charge we have never seen in the event history. Each
+     * one is revenue we cannot price, because the API exposes the discount but not
+     * the plan amount, so this should be 0 and is worth an alert when it is not.
+     */
+    unpricedSubscriptions: number;
+    /**
+     * How current the recheck is: the oldest read among the pairs it still revisits, on
+     * the same reasoning as `stalePairs`. Null before the first read.
+     */
+    oldestCheckedAt: string | null;
+}
+export interface RevenueSyncStatus {
+    currencyCode: string;
+    /** True when the service has no Partner token or is explicitly disabled. */
+    disabled: boolean;
+    feeds: SyncFeedStatus[];
+    apps: ReplayAppStatus[];
+    dirtyApps: number;
+    reconciliation: SubscriptionReconciliationStatus;
+    /**
+     * How current the raw layer is: the *oldest* watermark across the ingesting feeds,
+     * since the numbers are only complete up to whichever feed is furthest behind. The
+     * subscription recheck is not an ingesting feed and does not count towards it — see
+     * `reconciliation.oldestCheckedAt` for that.
+     */
+    watermarkAt: string | null;
+}
+/**
+ * Scope for the aggregate reads. `appGid` and `apiKey` both select a single app
+ * (`apiKey` being the Shopify client_id an app already knows about itself);
+ * passing neither reads the portfolio rollup.
+ */
+export interface RevenueScope {
+    appGid?: string;
+    apiKey?: string;
+}
+export interface MrrSeriesQuery extends RevenueScope {
+    /** Inclusive `YYYY-MM-DD`. Defaults to 90 days before `to`. */
+    from?: string;
+    /** Inclusive `YYYY-MM-DD`. Defaults to the latest computed day. */
+    to?: string;
+    /** Hard cap on returned points (most recent kept). Defaults to 400. */
+    limit?: number;
+}
+export interface MovementQuery extends RevenueScope {
+    from: string;
+    to: string;
+}
+export interface TrialFunnelQuery extends RevenueScope {
+    /** Inclusive `YYYY-MM` cohort bounds. Default: the last 12 months. */
+    fromMonth?: string;
+    toMonth?: string;
+}
+/**
+ * The read surface over derived Partner revenue, exposed by the same Worker as
+ * `IdentityClient` (entrypoint `MerchantRevenue`) because both own the same D1.
+ * Reads never touch the Partner API: they read tables the sync + replay have
+ * already built, so they are cheap and safe to call per request.
+ *
+ * `requestSync` / `requestReplay` are internal operator hooks, not app-facing;
+ * they only nudge the sync coordinator and return immediately.
+ */
+export interface RevenueClient {
+    getMerchantRevenue(shopDomain: string): Promise<MerchantRevenueSummary>;
+    getMrrSeries(query?: MrrSeriesQuery): Promise<MrrSeriesPoint[]>;
+    getMovementBreakdown(query: MovementQuery): Promise<MovementBreakdown>;
+    getTrialFunnel(query?: TrialFunnelQuery): Promise<TrialFunnelCohort[]>;
+    getSyncStatus(): Promise<RevenueSyncStatus>;
+    requestSync(reason?: string): Promise<void>;
+    requestReplay(appGid?: string): Promise<void>;
+}
+/** Empty summary for a store with no billing history (or no service). */
+export declare function emptyMerchantRevenue(shopDomain: string, currencyCode?: string): MerchantRevenueSummary;
+/**
+ * No-op client used when the service is unavailable (local dev) or explicitly
+ * disabled via `REVENUE_DISABLED`. Reads return empty rather than throwing so a
+ * dashboard renders zeroes instead of failing.
+ */
+export declare const NOOP_REVENUE: RevenueClient;
+/**
+ * Single seam for the revenue binding, mirroring `identity()`: returns the real
+ * binding when present and enabled, otherwise `NOOP_REVENUE`, so an app renders
+ * without the service bound.
+ */
+export declare function revenue(binding: RevenueClient | null | undefined, disabled?: boolean | string): RevenueClient;

package/dist/index.js

@@ -3,9 +3,10 @@
  *
  * Consumed by:
  *  - the `merchant-identity` service Worker, which implements `IdentityClient`
- *    against the shared D1, and
+ *    and `RevenueClient` against the shared D1, and
  *  - portfolio apps (DiscountKit, CodeBulk, Stackable), which call the service
- *    over an RPC service binding through the `identity()` seam below.
+ *    over an RPC service binding through the `identity()` / `revenue()` seams
+ *    below.
  *
  * This package holds only types + pure helpers, so it has no Cloudflare or
  * runtime dependencies and is safe to import anywhere.
@@ -78,3 +79,130 @@ export function identity(binding, disabled) {
     }
     return binding;
 }
+/* -------------------------------------------------------------------------- */
+/* Revenue: money representation                                              */
+/* -------------------------------------------------------------------------- */
+/**
+ * Every amount below is an integer in the currency's minor units (cents for
+ * USD), never a float, and is quoted in the service's report currency
+ * (`REVENUE_REPORT_CURRENCY`, USD by default). Amounts the Partner API reported
+ * in another currency are stored raw but excluded from these aggregates and
+ * counted in the sync status, so a non-zero `skippedCurrencyRows` means the
+ * numbers below are understating the portfolio.
+ */
+export const MINOR_UNIT_SCALE = 2;
+/**
+ * Render minor units as a plain decimal string (`123456` -> `"1234.56"`).
+ * String math throughout: passing these through a float would round-trip
+ * large amounts inexactly, and the point of minor units is exactness.
+ */
+export function minorUnitsToDecimal(minor, scale = MINOR_UNIT_SCALE) {
+    const negative = minor < 0;
+    const digits = Math.abs(Math.trunc(minor)).toString().padStart(scale + 1, '0');
+    const whole = digits.slice(0, digits.length - scale);
+    const fraction = scale > 0 ? `.${digits.slice(digits.length - scale)}` : '';
+    return `${negative ? '-' : ''}${whole}${fraction}`;
+}
+/* -------------------------------------------------------------------------- */
+/* Revenue: enums + sentinels                                                 */
+/* -------------------------------------------------------------------------- */
+/** `app_gid` sentinel for the portfolio-wide rollup row. */
+export const PORTFOLIO_APP_GID = '*';
+export const MOVEMENT_TYPES = [
+    'new',
+    'expansion',
+    'contraction',
+    'churn',
+    'reactivation',
+    'frozen',
+    'unfrozen',
+];
+/** Empty summary for a store with no billing history (or no service). */
+export function emptyMerchantRevenue(shopDomain, currencyCode = 'USD') {
+    return {
+        shopDomain,
+        shopKey: shopDomain,
+        currencyCode,
+        mrrMinor: 0,
+        grossMrrMinor: 0,
+        discountMinor: 0,
+        charges: [],
+        lifetimeGrossMinor: 0,
+        lifetimeNetMinor: 0,
+        firstPaidAt: null,
+        lastPaidAt: null,
+        activeTrials: 0,
+        computedAt: null,
+    };
+}
+/**
+ * No-op client used when the service is unavailable (local dev) or explicitly
+ * disabled via `REVENUE_DISABLED`. Reads return empty rather than throwing so a
+ * dashboard renders zeroes instead of failing.
+ */
+export const NOOP_REVENUE = {
+    async getMerchantRevenue(shopDomain) {
+        return emptyMerchantRevenue(shopDomain);
+    },
+    async getMrrSeries() {
+        return [];
+    },
+    async getMovementBreakdown(query) {
+        return {
+            from: query.from,
+            to: query.to,
+            appGid: query.appGid ?? PORTFOLIO_APP_GID,
+            openingMrrMinor: 0,
+            closingMrrMinor: 0,
+            newMinor: 0,
+            expansionMinor: 0,
+            contractionMinor: 0,
+            churnMinor: 0,
+            reactivationMinor: 0,
+            netMinor: 0,
+            counts: {
+                new: 0,
+                expansion: 0,
+                contraction: 0,
+                churn: 0,
+                reactivation: 0,
+                frozen: 0,
+                unfrozen: 0,
+            },
+        };
+    },
+    async getTrialFunnel() {
+        return [];
+    },
+    async getSyncStatus() {
+        return {
+            currencyCode: 'USD',
+            disabled: true,
+            feeds: [],
+            apps: [],
+            dirtyApps: 0,
+            reconciliation: {
+                checkedPairs: 0,
+                stalePairs: 0,
+                absentSubscriptions: 0,
+                unresolvedPairs: 0,
+                unpricedSubscriptions: 0,
+                oldestCheckedAt: null,
+            },
+            watermarkAt: null,
+        };
+    },
+    async requestSync() { },
+    async requestReplay() { },
+};
+/**
+ * Single seam for the revenue binding, mirroring `identity()`: returns the real
+ * binding when present and enabled, otherwise `NOOP_REVENUE`, so an app renders
+ * without the service bound.
+ */
+export function revenue(binding, disabled) {
+    if (!binding || disabled === true || disabled === 'true') {
+        return NOOP_REVENUE;
+    }
+    return binding;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@optizio/merchant-identity",
-  "version": "0.2.0",
-  "description": "Shared merchant/user identity types + RPC client contract for the merchant-hub portfolio.",
+  "version": "0.5.0",
+  "description": "Shared merchant/user identity + revenue types and RPC client contracts for the merchant-hub portfolio.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/optizio/merchant-hub.git",