@optizio/merchant-identity 0.5.2 → 0.7.0

package/dist/index.d.ts

@@ -472,3 +472,491 @@ export declare const NOOP_REVENUE: RevenueClient;
  * without the service bound.
  */
 export declare function revenue(binding: RevenueClient | null | undefined, disabled?: boolean | string): RevenueClient;
+/**
+ * One app's affiliate program. The only supported economics are a percentage
+ * of transaction net, lifetime; `defaultRateBps` is data, not a hard-coded
+ * calculation, and each referral snapshots the rate at claim time so a future
+ * default change does not alter existing referrals.
+ */
+export interface AffiliateProgram {
+    id: string;
+    /** References `partner_apps.app_gid`; unique per app in this stage. */
+    appGid: string;
+    name: string;
+    /** Percentage of transaction net in basis points. 2000 = 20%. */
+    defaultRateBps: number;
+    /** 'active' | 'inactive'. */
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * One portfolio-wide person or business receiving commission. There is
+ * deliberately no status/archive field: `payoutHold` with a reason is the only
+ * mechanism that pauses payments, and it does NOT terminate lifetime referral
+ * rights — commissions keep accruing while held. Email is searchable but is
+ * not identity.
+ */
+export interface Affiliate {
+    id: string;
+    name: string;
+    /** Contact email; separate from the payout destination. */
+    email: string | null;
+    payoutHold: boolean;
+    payoutHoldReason: string | null;
+    /** e.g. 'paypal' or 'external_account'; null until configured. */
+    payoutMethod: string | null;
+    /** A PayPal email or opaque external account reference. No bank secrets. */
+    payoutDestination: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** An affiliate's participation in one app's program. */
+export interface AffiliateMembership {
+    id: string;
+    affiliateId: string;
+    programId: string;
+    /** 'active' | 'inactive'. Does not implicitly cancel existing referrals. */
+    status: string;
+    joinedAt: string | null;
+    /** Original referral codes with their source namespaces, if imported. */
+    legacyCodes: {
+        source: string;
+        code: string;
+    }[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * The continuing claim: this affiliate earns commission from this shop for
+ * this app. `referredAt` is the historical referral date; `accrualFrom` is the
+ * local calculation boundary — they are not interchangeable. Uninstall,
+ * cancellation, freeze, and reinstall do not remove attribution.
+ */
+export interface AffiliateReferral {
+    id: string;
+    membershipId: string;
+    appGid: string;
+    /** Normalized (lowercase, protocol-less) myshopify host. */
+    shopDomain: string;
+    /** Verified Partner shop GID; null when redacted or unknown. */
+    shopGid: string | null;
+    referredAt: string | null;
+    /** Snapshot of the program rate at claim creation (2000 = 20%). */
+    rateBps: number;
+    accrualFrom: string;
+    /** 'active' | 'ended'. */
+    status: string;
+    endedAt: string | null;
+    endReason: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Append-only money owed. `kind` is 'commission' | 'adjustment'; `amountMinor`
+ * is signed (adjustments may be negative). Corrections append entries — an
+ * earned amount is never edited or deleted, even before payout. All
+ * `*Minor` fields are integer minor units of `currencyCode`.
+ */
+export interface AffiliateLedgerEntry {
+    id: string;
+    affiliateId: string;
+    /** Null for manual adjustments, which have no program context. */
+    programId: string | null;
+    /** Null for historical/manual records. */
+    referralId: string | null;
+    kind: 'commission' | 'adjustment';
+    amountMinor: number;
+    currencyCode: string;
+    /** Business date the entry concerns; not the insert timestamp. */
+    effectiveAt: string;
+    recordedAt: string;
+    partnerTransactionGid: string | null;
+    /** Snapshots preserved for sweep change detection. */
+    netMinorSnapshot: number | null;
+    rateBpsSnapshot: number | null;
+    /** 1 = 20% of netAmount from cutover onward; null for imports. */
+    calculationVersion: number | null;
+    /** For a reversing adjustment: the commission it reverses. */
+    relatedEntryId: string | null;
+    reason: string | null;
+    actorId: string | null;
+}
+/**
+ * A historical payment or a fixed proposal for a manual payment. Payouts span
+ * apps; their items retain app-level attribution. `destinationSnapshot` is
+ * frozen at preparation so later contact changes cannot rewrite history.
+ */
+export interface AffiliatePayout {
+    id: string;
+    affiliateId: string;
+    currencyCode: string;
+    /** `YYYY-MM` preparation cycle, null for imported history. */
+    cycleMonth: string | null;
+    /** Liability cutoff the proposal was fixed at. */
+    cutoffAt: string | null;
+    /** 'pending' | 'processing' | 'paid' | 'cancelled'. `paid` is terminal. */
+    status: 'pending' | 'processing' | 'paid' | 'cancelled';
+    amountMinor: number;
+    paymentMethod: string | null;
+    destinationSnapshot: string | null;
+    /** Legacy invoice number or payment-provider reference, if any. */
+    externalReference: string | null;
+    preparedAt: string | null;
+    processingAt: string | null;
+    paidAt: string | null;
+    paidBy: string | null;
+    failureReason: string | null;
+}
+/** One payout's allocation of a ledger entry; supports imported partials. */
+export interface AffiliatePayoutItem {
+    payoutId: string;
+    ledgerEntryId: string;
+    /** Signed: negative entries can be settled by negative allocations. */
+    allocatedMinor: number;
+    /** Null while reserved; set when a cancellation released it. */
+    releasedAt: string | null;
+}
+/**
+ * Per affiliate and currency. Negative balances are valid and carry forward;
+ * nothing here is clamped to zero. Freshness is explicit so a reader can tell
+ * a genuine zero from stale or unavailable data.
+ */
+export interface AffiliateBalance {
+    affiliateId: string;
+    currencyCode: string;
+    earnedMinor: number;
+    adjustmentsMinor: number;
+    /** earned + adjustments − settled paid allocations. */
+    outstandingMinor: number;
+    /** Allocations in pending or processing payouts. */
+    reservedMinor: number;
+    /** outstanding − reserved. */
+    availableMinor: number;
+    /** How current the ledger behind these numbers is (last recorded_at). */
+    freshness: string | null;
+}
+/**
+ * Opaque cursor for list endpoints. Servers return the next page's cursor
+ * alongside results; clients pass it back verbatim. Null on the last page.
+ */
+export interface AffiliateListCursor {
+    cursor: string | null;
+    /** Hard cap on returned rows. Servers clamp to their own bound. */
+    limit?: number;
+}
+/** Common filters for affiliate list queries; all optional. */
+export interface AffiliateListFilters {
+    affiliateId?: string;
+    appGid?: string;
+    status?: string;
+    /** Inclusive UTC ISO bound. */
+    from?: string;
+    /** Inclusive UTC ISO bound. */
+    to?: string;
+}
+export interface AffiliateListQuery extends AffiliateListCursor, AffiliateListFilters {
+}
+/** Page-shaped result; every list RPC returns this so pagination is uniform. */
+export interface AffiliatePage<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+/**
+ * Update an affiliate's contact and payout settings. Only the fields present
+ * are changed. Setting or clearing a hold takes effect for future payouts
+ * only; accrued obligations are unaffected.
+ */
+export interface AffiliateUpdateInput {
+    affiliateId: string;
+    name?: string;
+    email?: string | null;
+    payoutHold?: boolean;
+    payoutHoldReason?: string | null;
+    payoutMethod?: string | null;
+    payoutDestination?: string | null;
+    /** Required when `payoutHold` changes: why the operator moved it. */
+    reason?: string;
+    actorId: string;
+}
+/** Set the minimum payout amount (minor units, USD this stage). */
+export interface AffiliatePayoutPolicyInput {
+    /** Null disables preparation until explicitly configured. */
+    minimumPayoutMinor: number | null;
+    reason: string;
+    actorId: string;
+}
+/**
+ * Stage a Shoffi/Mantle export for validation. The payload is the original
+ * records verbatim (no secrets); content is hashed server-side for
+ * repeat-import detection.
+ */
+export interface AffiliateImportBatchInput {
+    source: 'shoffi' | 'mantle';
+    sourceAccount: string | null;
+    /** UTC timestamp the source exported at, when known. */
+    exportedAt: string | null;
+    /** Source schema version of the export shape, when known. */
+    schemaVersion: string | null;
+    records: unknown[];
+    idempotencyKey: string;
+    actorId: string;
+}
+/** Activate a validated import; partial data must not leak into balances. */
+export interface AffiliateImportActivateInput {
+    batchId: string;
+    idempotencyKey: string;
+    actorId: string;
+}
+/** Explicitly map one source record to a canonical entity. */
+export interface AffiliateImportResolveInput {
+    sourceRecordId: string;
+    canonicalEntityType: string;
+    canonicalEntityId: string;
+    reason: string;
+    actorId: string;
+}
+/**
+ * One approved program in the first canonical relationship seed. The app
+ * must already exist in Partner data; this operation does not create apps.
+ */
+export interface AffiliateRelationshipSeedProgramInput {
+    id: string;
+    /** The app-local Shoffi identifier explicitly mapped to this Partner app. */
+    sourceAppId: string;
+    appGid: string;
+    name: string;
+    defaultRateBps: number;
+    status: 'active' | 'inactive';
+    /** Approved UTC commission cutover for this app's referrals. */
+    cutoverAt: string;
+}
+/**
+ * An approved canonical affiliate. Relationship migration keeps every
+ * affiliate on payout hold until payout policy and historical balances have
+ * separately been approved.
+ */
+export interface AffiliateRelationshipSeedAffiliateInput {
+    id: string;
+    name: string;
+    email: string | null;
+    payoutHoldReason: string;
+}
+/**
+ * Maps one app-scoped Shoffi relation identity to an approved canonical
+ * affiliate/program membership. The source identity is retained in the seed
+ * audit record and must not be inferred from display names or emails.
+ */
+export interface AffiliateRelationshipSeedMembershipInput {
+    id: string;
+    affiliateId: string;
+    programId: string;
+    sourceAppId: string;
+    sourceRelationId: string;
+    joinedAt: string | null;
+    status: 'active' | 'inactive';
+    legacyCodes: {
+        source: string;
+        code: string;
+    }[];
+}
+/** An approved continuing or ended Shoffi referral relationship. */
+export interface AffiliateRelationshipSeedReferralInput {
+    id: string;
+    membershipId: string;
+    appGid: string;
+    shopDomain: string;
+    shopGid: string | null;
+    referredAt: string | null;
+    rateBps: number;
+    accrualFrom: string;
+    status: 'active' | 'ended';
+    endedAt: string | null;
+    endReason: string | null;
+}
+/**
+ * The complete operator-reviewed canonical relationship seed. It deliberately
+ * excludes historical commissions, payouts, and payout items.
+ */
+export interface AffiliateRelationshipSeedInput {
+    /** The reviewed Shoffi account scope that supplied the relation IDs. */
+    sourceAccount: string;
+    programs: AffiliateRelationshipSeedProgramInput[];
+    affiliates: AffiliateRelationshipSeedAffiliateInput[];
+    memberships: AffiliateRelationshipSeedMembershipInput[];
+    referrals: AffiliateRelationshipSeedReferralInput[];
+    idempotencyKey: string;
+    reason: string;
+    actorId: string;
+}
+export interface AffiliateRelationshipSeedResult {
+    programIds: string[];
+    affiliateIds: string[];
+    membershipIds: string[];
+    referralIds: string[];
+}
+/** Ask for a (catch-up) commission sweep pass; returns immediately. */
+export interface AffiliateSweepInput {
+    /** Restrict the pass to one app, null = all. */
+    appGid: string | null;
+    reason: string;
+    actorId: string;
+}
+/** The month to preview/prepare payouts for; defaults to the latest cycle. */
+export interface AffiliatePayoutCycleInput {
+    /** `YYYY-MM`. */
+    cycleMonth: string;
+    idempotencyKey: string;
+    actorId: string;
+}
+/** Dry-run of monthly preparation; writes nothing. */
+export interface AffiliatePayoutPreviewInput extends AffiliatePayoutCycleInput {
+}
+/** Begin a manual payment for a proposed payout (pending -> processing). */
+export interface AffiliateBeginPayoutInput {
+    payoutId: string;
+    idempotencyKey: string;
+    reason: string;
+    actorId: string;
+}
+/**
+ * Confirm a payout as paid (terminal). Requires a payment reference, actual
+ * date, and actor; duplicate identical confirmations are idempotent and
+ * conflicting ones fail.
+ */
+export interface AffiliateRecordPaidInput {
+    payoutId: string;
+    externalReference: string;
+    paidAt: string;
+    idempotencyKey: string;
+    reason: string;
+    actorId: string;
+}
+/** Record that no transfer happened (processing -> pending). */
+export interface AffiliateRecordNotSentInput {
+    payoutId: string;
+    failureReason: string;
+    idempotencyKey: string;
+    reason: string;
+    actorId: string;
+}
+/** Cancel a proposed payout, releasing its reservations (pending -> cancelled). */
+export interface AffiliateCancelPayoutInput {
+    payoutId: string;
+    idempotencyKey: string;
+    reason: string;
+    actorId: string;
+}
+/**
+ * Append a signed manual adjustment to an affiliate's ledger. Adjustments
+ * may be negative and may concern already-paid commissions; they affect the
+ * remaining balance, not the past payment.
+ */
+export interface AffiliateAdjustmentInput {
+    affiliateId: string;
+    currencyCode: string;
+    /** Signed minor units. */
+    amountMinor: number;
+    effectiveAt: string;
+    reason: string;
+    actorId: string;
+    /** Optionally link the commission entry this adjustment reverses. */
+    relatedEntryId: string | null;
+    idempotencyKey: string;
+}
+/** A proposed monthly payout from a preview run; writes nothing. */
+export interface AffiliatePayoutProposal {
+    affiliateId: string;
+    currencyCode: string;
+    cycleMonth: string;
+    cutoffAt: string;
+    amountMinor: number;
+    /** Why this affiliate was skipped, when it was. */
+    skippedReason: string | null;
+}
+/**
+ * The read surface over affiliate data, exposed by the same Worker as
+ * `IdentityClient` and `RevenueClient` (entrypoint `MerchantAffiliates`).
+ * Reads never trigger computation or call Shopify; they read tables the
+ * sweep and import jobs have already built.
+ */
+export interface AffiliateClient {
+    listPrograms(): Promise<AffiliateProgram[]>;
+    listAffiliates(query?: AffiliateListQuery): Promise<AffiliatePage<Affiliate>>;
+    getAffiliate(id: string): Promise<Affiliate | null>;
+    listReferrals(query?: AffiliateListQuery): Promise<AffiliatePage<AffiliateReferral>>;
+    getAffiliateBalance(input: {
+        affiliateId: string;
+        currencyCode?: string;
+    }): Promise<AffiliateBalance[]>;
+    listLedgerEntries(query?: AffiliateListQuery): Promise<AffiliatePage<AffiliateLedgerEntry>>;
+    listPayouts(query?: AffiliateListQuery): Promise<AffiliatePage<AffiliatePayout>>;
+    getPayout(id: string): Promise<AffiliatePayout | null>;
+    getAffiliateStatus(): Promise<AffiliateDomainStatus>;
+}
+/** Operational summary for the affiliate domain as a whole. */
+export interface AffiliateDomainStatus {
+    /** Whether the affiliate feature is enabled in this deployment. */
+    enabled: boolean;
+    /** False until a payout threshold has been explicitly configured. */
+    payoutThresholdConfigured: boolean;
+    /** Count of import batches not yet activated. */
+    pendingImportBatches: number;
+    /** Count of unresolved reconciliation issues across jobs. */
+    openIssues: number;
+}
+/**
+ * Trusted-operator write surface (entrypoint `MerchantAffiliateAdmin`).
+ * Unlike `NOOP_REVENUE`-style read clients, an unavailable admin client MUST
+ * fail rather than pretend an import or payment was recorded.
+ */
+export interface AffiliateAdminClient {
+    updateAffiliate(input: AffiliateUpdateInput): Promise<Affiliate>;
+    setPayoutPolicy(input: AffiliatePayoutPolicyInput): Promise<void>;
+    seedRelationship(input: AffiliateRelationshipSeedInput): Promise<AffiliateRelationshipSeedResult>;
+    stageImportBatch(input: AffiliateImportBatchInput): Promise<{
+        batchId: string;
+    }>;
+    validateImport(id: string): Promise<{
+        valid: boolean;
+        errorCount: number;
+    }>;
+    activateImport(input: AffiliateImportActivateInput): Promise<void>;
+    resolveImportRecord(input: AffiliateImportResolveInput): Promise<void>;
+    requestCommissionSweep(input: AffiliateSweepInput): Promise<void>;
+    previewMonthlyPayouts(input: AffiliatePayoutPreviewInput): Promise<AffiliatePayoutProposal[]>;
+    prepareMonthlyPayouts(input: AffiliatePayoutCycleInput): Promise<AffiliatePayout[]>;
+    beginPayout(input: AffiliateBeginPayoutInput): Promise<AffiliatePayout>;
+    recordPayoutPaid(input: AffiliateRecordPaidInput): Promise<AffiliatePayout>;
+    recordPayoutNotSent(input: AffiliateRecordNotSentInput): Promise<AffiliatePayout>;
+    cancelPayout(input: AffiliateCancelPayoutInput): Promise<AffiliatePayout>;
+    recordAdjustment(input: AffiliateAdjustmentInput): Promise<AffiliateLedgerEntry>;
+}
+/**
+ * Deliberately narrow import-staging surface for the Access-protected
+ * dashboard. It does not expose validation, activation, payouts, or any
+ * other affiliate administration operation.
+ */
+export interface AffiliateImportStagingClient {
+    stageImportBatch(input: AffiliateImportBatchInput): Promise<{
+        batchId: string;
+    }>;
+}
+/**
+ * The one rejection every `UNAVAILABLE_AFFILIATE_ADMIN` method throws: an
+ * unavailable affiliate write client must fail, never pretend an import,
+ * adjustment, or payment was recorded (spec §7).
+ */
+export declare const AFFILIATE_ADMIN_UNAVAILABLE_MESSAGE = "The affiliate admin service is unavailable; no import, adjustment, or payment was recorded";
+/**
+ * The admin client standing in when the affiliate write binding is absent or
+ * disabled. Unlike `NOOP_IDENTITY`/`NOOP_REVENUE` (whose reads render empty),
+ * every method here REJECTS: financial writes may never silently no-op.
+ */
+export declare const UNAVAILABLE_AFFILIATE_ADMIN: AffiliateAdminClient;
+/**
+ * Single seam for the affiliate admin binding, mirroring `identity()` /
+ * `revenue()` — but the fallback REJECTS rather than no-ops, because a
+ * pretended import or payment is worse than a failed call.
+ */
+export declare function affiliateAdmin(binding: AffiliateAdminClient | null | undefined): AffiliateAdminClient;

package/dist/index.js

@@ -206,3 +206,77 @@ export function revenue(binding, disabled) {
     }
     return binding;
 }
+/* -------------------------------------------------------------------------- */
+/* Affiliates: unavailable admin client                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * The one rejection every `UNAVAILABLE_AFFILIATE_ADMIN` method throws: an
+ * unavailable affiliate write client must fail, never pretend an import,
+ * adjustment, or payment was recorded (spec §7).
+ */
+export const AFFILIATE_ADMIN_UNAVAILABLE_MESSAGE = 'The affiliate admin service is unavailable; no import, adjustment, or payment was recorded';
+function unavailable() {
+    throw new Error(AFFILIATE_ADMIN_UNAVAILABLE_MESSAGE);
+}
+/**
+ * The admin client standing in when the affiliate write binding is absent or
+ * disabled. Unlike `NOOP_IDENTITY`/`NOOP_REVENUE` (whose reads render empty),
+ * every method here REJECTS: financial writes may never silently no-op.
+ */
+export const UNAVAILABLE_AFFILIATE_ADMIN = {
+    async updateAffiliate() {
+        unavailable();
+    },
+    async setPayoutPolicy() {
+        unavailable();
+    },
+    async seedRelationship() {
+        unavailable();
+    },
+    async stageImportBatch() {
+        unavailable();
+    },
+    async validateImport() {
+        unavailable();
+    },
+    async activateImport() {
+        unavailable();
+    },
+    async resolveImportRecord() {
+        unavailable();
+    },
+    async requestCommissionSweep() {
+        unavailable();
+    },
+    async previewMonthlyPayouts() {
+        unavailable();
+    },
+    async prepareMonthlyPayouts() {
+        unavailable();
+    },
+    async beginPayout() {
+        unavailable();
+    },
+    async recordPayoutPaid() {
+        unavailable();
+    },
+    async recordPayoutNotSent() {
+        unavailable();
+    },
+    async cancelPayout() {
+        unavailable();
+    },
+    async recordAdjustment() {
+        unavailable();
+    },
+};
+/**
+ * Single seam for the affiliate admin binding, mirroring `identity()` /
+ * `revenue()` — but the fallback REJECTS rather than no-ops, because a
+ * pretended import or payment is worse than a failed call.
+ */
+export function affiliateAdmin(binding) {
+    if (!binding)
+        return UNAVAILABLE_AFFILIATE_ADMIN;
+    return binding;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optizio/merchant-identity",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Shared merchant/user identity + revenue types and RPC client contracts for the merchant-hub portfolio.",
   "repository": {
     "type": "git",