Outcomes & reason codes

import { credits, encodeAmount, spend, userActor } from '@pwngh/economy-lab';

import type { Economy } from '@pwngh/economy-lab';
import type { SnippetReport } from './context.ts';

// A rejection is data, not an exception: the reason code verbatim, plus the typed
// figures it carries — here the funds gate reporting what the spend needs against what
// the wallet has.
export async function run(economy: Economy): Promise<SnippetReport> {
  const orderId = `ord_${crypto.randomUUID().slice(0, 8)}`;
  const outcome = await economy.submit(
    spend({
      idempotencyKey: orderId,
      actor: userActor('usr_newcomer'),
      orderId,
      buyerId: 'usr_newcomer', // an empty wallet
      sku: 'First Purchase',
      price: credits(250),
      recipients: [{ sellerId: 'usr_nova', shareBps: 10_000 }],
    }),
  );

  if (outcome.status !== 'rejected' || outcome.detail.reason !== 'INSUFFICIENT_FUNDS') {
    return {
      lines: [`status: ${outcome.status} — the newcomer has funds now; reset the economy to rerun`],
      consolePath: '/market',
    };
  }

  return {
    lines: [
      `status: ${outcome.status}`,
      `reason: ${outcome.detail.reason}`,
      `need: ${encodeAmount(outcome.detail.need)} · have: ${encodeAmount(outcome.detail.have)}`,
    ],
    consolePath: '/market',
  };
}

import {
  cancelSubscription,
  createEconomy,
  credits,
  memoryPorts,
  refund,
  revokeEntitlement,
  spend,
  subscribe,
  systemActor,
  topUp,
  userActor,
} from '@pwngh/economy-lab';

import type { Outcome } from '@pwngh/economy-lab';
import type { SnippetReport } from './context.ts';

// The record-keyed declines, produced in one sitting against a private little economy: each
// answer is the code plus the record it couldn't find or refuses to double-book.
export async function run(): Promise<SnippetReport> {
  const economy = createEconomy(memoryPorts({ signingKey: 'docs-signing-key' }));
  const buyer = userActor('usr_r');
  await economy.submit(
    topUp({
      idempotencyKey: 'idem_fund',
      actor: systemActor('docs'),
      userId: 'usr_r',
      amount: credits(1_000),
      source: 'card',
    }),
  );

  const order = (idempotencyKey: string) =>
    spend({
      idempotencyKey,
      actor: buyer,
      orderId: 'ord_r1',
      buyerId: 'usr_r',
      sku: 'Poster',
      price: credits(100),
      recipients: [{ sellerId: 'usr_s', shareBps: 10_000 }],
    });
  await economy.submit(order('idem_first')); // commits and records the sale
  const dupOrder = await economy.submit(order('idem_lost_the_key'));

  const ghostRefund = await economy.submit(
    refund({ idempotencyKey: 'idem_gr', actor: systemActor('docs'), orderId: 'ord_ghost' }),
  );
  const ghostCancel = await economy.submit(
    cancelSubscription({ idempotencyKey: 'idem_gc', actor: buyer, subscriptionId: 'sub_ghost' }),
  );

  const club = (idempotencyKey: string) =>
    subscribe({
      idempotencyKey,
      actor: buyer,
      userId: 'usr_r',
      sellerId: 'usr_s',
      sku: 'Club',
      price: credits(300),
      periodMs: 2_592_000_000,
    });
  await economy.submit(club('idem_join')); // the one active subscription
  const twice = await economy.submit(club('idem_join_again'));

  const unowned = await economy.submit(
    revokeEntitlement({
      idempotencyKey: 'idem_rv',
      actor: systemActor('docs'),
      userId: 'usr_r',
      sku: 'sku_never_granted',
    }),
  );
  await economy.close();

  const reason = (o: Outcome) => (o.status === 'rejected' ? o.detail.reason : o.status);
  const detail = (o: Outcome) => JSON.stringify(o.status === 'rejected' ? o.detail : {});
  return {
    lines: [
      `same order, new key: ${reason(dupOrder)} — detail ${detail(dupOrder)}`,
      `refund of no sale:   ${reason(ghostRefund)} — detail ${detail(ghostRefund)}`,
      `cancel of no sub:    ${reason(ghostCancel)} — detail ${detail(ghostCancel)}`,
      `subscribe twice:     ${reason(twice)} — detail ${detail(twice)}`,
      `revoke unowned sku:  ${reason(unowned)} — detail ${detail(unowned)}`,
    ],
    consolePath: '/market',
  };
}

import {
  adjust,
  createEconomy,
  credits,
  earned,
  memoryPorts,
  operatorActor,
  requestPayout,
  userActor,
} from '@pwngh/economy-lab';
import { encodeAmounts } from '@pwngh/economy-lab/store-kit';

import type { Outcome } from '@pwngh/economy-lab';
import type { SnippetReport } from './context.ts';

// The three payout gates, tripped in order on a purpose-built economy: a 100-credit minimum, a
// 7-day gap between requests, and a payee directory that has cleared only one seller.
export async function run(): Promise<SnippetReport> {
  const economy = createEconomy({
    ...memoryPorts({
      signingKey: 'docs-signing-key',
      config: {
        payoutMinimumEarnedMinor: 10_000n, // 100 credits
        payoutMinIntervalMs: 7 * 86_400_000,
      },
    }),
    payees: {
      status: async (userId) => ({ state: userId === 'usr_cleared' ? 'CLEARED' : 'PENDING' }),
    },
  });
  await economy.submit(
    adjust({
      idempotencyKey: 'idem_seed',
      actor: operatorActor('op_docs'),
      account: earned('usr_cleared'),
      amount: credits(200),
      reason: 'docs: seed earnings',
    }),
  );

  const request = (userId: string, amount: number, key: string) =>
    economy.submit(
      requestPayout({
        idempotencyKey: key,
        actor: userActor(userId),
        userId,
        amount: credits(amount),
      }),
    );

  const tooSmall = await request('usr_cleared', 50, 'idem_small'); // under the 100 minimum
  await request('usr_cleared', 150, 'idem_ok'); // 150 clears every gate
  const tooSoon = await request('usr_cleared', 150, 'idem_again'); // clears the minimum, inside the 7-day gap
  const unverified = await request('usr_pending', 150, 'idem_pending');
  await economy.close();

  const report = (label: string, o: Outcome) =>
    o.status === 'rejected'
      ? `${label}: ${o.detail.reason} — detail ${JSON.stringify(encodeAmounts(o.detail))}`
      : `${label}: ${o.status}`;
  return {
    lines: [
      report('50 against the 100 minimum', tooSmall),
      report('a second ask, day one    ', tooSoon),
      report('an uncleared payee       ', unverified),
    ],
    consolePath: '/payouts',
  };
}

import {
  createEconomy,
  credits,
  memoryPorts,
  spend,
  systemActor,
  topUp,
  userActor,
} from '@pwngh/economy-lab';

import type { SnippetReport } from './context.ts';

// FUNDS_IMMATURE, produced by giving card credit a three-day holding window: the money is
// there, it just hasn't cleared, and the detail says when it will have.
export async function run(): Promise<SnippetReport> {
  const economy = createEconomy(
    memoryPorts({
      signingKey: 'docs-signing-key',
      config: { maturityHorizonMs: { card: 3 * 86_400_000 } },
    }),
  );
  await economy.submit(
    topUp({
      idempotencyKey: 'idem_fund',
      actor: systemActor('docs'),
      userId: 'usr_m',
      amount: credits(100), // in the wallet, but held for three days
      source: 'card',
    }),
  );
  const outcome = await economy.submit(
    spend({
      idempotencyKey: 'idem_try',
      actor: userActor('usr_m'),
      orderId: 'ord_m1',
      buyerId: 'usr_m',
      sku: 'Poster',
      price: credits(50),
      recipients: [{ sellerId: 'usr_s', shareBps: 10_000 }],
    }),
  );
  await economy.close();

  if (outcome.status !== 'rejected' || outcome.detail.reason !== 'FUNDS_IMMATURE') {
    return { lines: [`status: ${outcome.status}`], consolePath: '/market' };
  }
  return {
    lines: [
      `status: rejected (${outcome.detail.reason})`,
      `detail: ${JSON.stringify(outcome.detail)} — clears ${new Date(outcome.detail.availableAt).toISOString()}`,
    ],
    consolePath: '/market',
  };
}

import {
  createEconomy,
  credits,
  memoryPorts,
  spend,
  systemActor,
  topUp,
  userActor,
} from '@pwngh/economy-lab';

import type { SnippetReport } from './context.ts';

// ECONOMY_PAUSED, inside a live maintenance window: the user's discretionary write waits, the
// system's settlement does not, and the detail says when writes resume.
export async function run(): Promise<SnippetReport> {
  const resumesAt = Date.now() + 3_600_000; // the window closes in an hour
  const economy = createEconomy(
    memoryPorts({
      signingKey: 'docs-signing-key',
      config: { pauseStartMs: Date.now() - 1_000, pauseEndMs: resumesAt },
    }),
  );
  const funded = await economy.submit(
    topUp({
      idempotencyKey: 'idem_fund',
      actor: systemActor('payments'),
      userId: 'usr_p',
      amount: credits(100),
      source: 'card',
    }),
  );
  const paused = await economy.submit(
    spend({
      idempotencyKey: 'idem_try',
      actor: userActor('usr_p'),
      orderId: 'ord_p1',
      buyerId: 'usr_p',
      sku: 'Poster',
      price: credits(50),
      recipients: [{ sellerId: 'usr_s', shareBps: 10_000 }],
    }),
  );
  await economy.close();

  const minutes =
    paused.status === 'rejected' &&
    paused.detail.reason === 'ECONOMY_PAUSED' &&
    paused.detail.resumesAt !== null
      ? Math.round((paused.detail.resumesAt - Date.now()) / 60_000)
      : null;
  return {
    lines: [
      `system top-up in the window: ${funded.status} — settlement is never paused`,
      paused.status === 'rejected'
        ? `user spend in the window:    rejected (${paused.detail.reason})${minutes === null ? '' : ` — resumes in ~${minutes} min`}`
        : `user spend in the window:    ${paused.status}`,
    ],
    consolePath: '/controls',
  };
}