Subscriptions

npm install --global @parix/cli@latest
parix --version
parix auth login
parix auth status
parix database list --json

export PARIX_DATABASE_ID="db_replace_with_database_uuid"

[
  {
    "id": "81000000000000000001",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "reserved": 0,
    "ledger": 7300,
    "code": 1101,
    "flags": 8,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000002",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "510001",
    "user_data_64": "202608",
    "user_data_32": 1,
    "reserved": 0,
    "ledger": 7300,
    "code": 1102,
    "flags": 10,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000003",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "reserved": 0,
    "ledger": 7300,
    "code": 1103,
    "flags": 8,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000011",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 0,
    "reserved": 0,
    "ledger": 840,
    "code": 1201,
    "flags": 8,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000012",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "510001",
    "user_data_64": "0",
    "user_data_32": 840,
    "reserved": 0,
    "ledger": 840,
    "code": 1202,
    "flags": 10,
    "timestamp": "0"
  },
  {
    "id": "81000000000000000013",
    "debits_pending": "0",
    "debits_posted": "0",
    "credits_pending": "0",
    "credits_posted": "0",
    "user_data_128": "0",
    "user_data_64": "0",
    "user_data_32": 840,
    "reserved": 0,
    "ledger": 840,
    "code": 1203,
    "flags": 8,
    "timestamp": "0"
  }
]

parix tb create-accounts "$PARIX_DATABASE_ID" \
  --file ./subscription-accounts.json \
  --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 82000000000000000001 \
  --from 81000000000000000001 \
  --to 81000000000000000002 \
  --amount 100000 \
  --ledger 7300 \
  --code 2101 \
  --user-data-128 510001 \
  --user-data-64 202608 \
  --user-data-32 1 \
  --json

[
  {
    "id": "82000000000000000002",
    "debit_account_id": "81000000000000000002",
    "credit_account_id": "81000000000000000003",
    "amount": "1250",
    "pending_id": "0",
    "user_data_128": "510001",
    "user_data_64": "202608",
    "user_data_32": 1,
    "timeout": 0,
    "ledger": 7300,
    "code": 2102,
    "flags": 0,
    "timestamp": "0"
  },
  {
    "id": "82000000000000000003",
    "debit_account_id": "81000000000000000002",
    "credit_account_id": "81000000000000000003",
    "amount": "750",
    "pending_id": "0",
    "user_data_128": "510001",
    "user_data_64": "202608",
    "user_data_32": 1,
    "timeout": 0,
    "ledger": 7300,
    "code": 2102,
    "flags": 0,
    "timestamp": "0"
  }
]

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --file ./subscription-usage-events.json \
  --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 83000000000000000001 \
  --from 81000000000000000011 \
  --to 81000000000000000012 \
  --amount 4900 \
  --ledger 840 \
  --code 3101 \
  --user-data-128 510001 \
  --user-data-32 840 \
  --json

parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 83000000000000000002 \
  --from 81000000000000000012 \
  --to 81000000000000000013 \
  --amount 4900 \
  --ledger 840 \
  --code 3102 \
  --user-data-128 510001 \
  --user-data-64 202608 \
  --user-data-32 840 \
  --json

# Credit 100 units back to the allowance for a reviewed overcharge case.
parix tb create-transfers "$PARIX_DATABASE_ID" \
  --id 82000000000000000010 \
  --from 81000000000000000003 \
  --to 81000000000000000002 \
  --amount 100 \
  --ledger 7300 \
  --code 2104 \
  --user-data-128 510001 \
  --user-data-64 202608 \
  --user-data-32 1 \
  --json

parix tb query-transfers "$PARIX_DATABASE_ID" \
  --ledger 7300 \
  --code 2102 \
  --user-data-128 510001 \
  --user-data-64 202608 \
  --user-data-32 1 \
  --limit 100 \
  --json

parix tb query-transfers "$PARIX_DATABASE_ID" \
  --ledger 840 \
  --code 3102 \
  --user-data-128 510001 \
  --user-data-64 202608 \
  --user-data-32 840 \
  --limit 100 \
  --json

import type {
  Account,
  Client,
  CreateAccountResult,
  CreateTransferResult,
  Transfer,
} from '@parix/tigerbeetle-node';
import {
  AccountFlags,
  CreateTransferError,
  QueryFilterFlags,
  TransferFlags,
  createClient,
} from '@parix/tigerbeetle-node';

const USAGE_LEDGER = 7300;
const MONEY_LEDGER = 840;
const ACCOUNT_CODE = {
  grantSource: 1101,
  subscriberAllowance: 1102,
  usageSink: 1103,
  collectionSource: 1201,
  prepaidBalance: 1202,
  billingClearing: 1203,
} as const;
const TRANSFER_CODE = {
  grant: 2101,
  consume: 2102,
  usageAdjust: 2103,
  usageRefund: 2104,
  fundsReceived: 3101,
  invoiceCharge: 3102,
  moneyAdjust: 3103,
  moneyRefund: 3104,
} as const;

interface PersistedSubscriptionIds {
  subscriptionId: bigint;
  periodId: bigint;
  sourceEventId: string;
  providerEventId: string;
  invoiceId: string;
  grantSourceAccountId: bigint;
  subscriberAllowanceAccountId: bigint;
  usageSinkAccountId: bigint;
  collectionSourceAccountId: bigint;
  prepaidBalanceAccountId: bigint;
  billingClearingAccountId: bigint;
  grantTransferId: bigint;
  usageTransferId: bigint;
  fundsReceivedTransferId: bigint;
  invoiceChargeTransferId: bigint;
}

// Replace these demo literals with one durable subscription-period record and
// its source-event, provider-event, and invoice mappings.
const persisted: PersistedSubscriptionIds = {
  subscriptionId: 510001n,
  periodId: 202608n,
  sourceEventId: 'usage_evt_01JEXAMPLE',
  providerEventId: 'provider_evt_01JEXAMPLE',
  invoiceId: 'inv_2026_08_510001',
  grantSourceAccountId: 81000000000000000001n,
  subscriberAllowanceAccountId: 81000000000000000002n,
  usageSinkAccountId: 81000000000000000003n,
  collectionSourceAccountId: 81000000000000000011n,
  prepaidBalanceAccountId: 81000000000000000012n,
  billingClearingAccountId: 81000000000000000013n,
  grantTransferId: 82000000000000000001n,
  usageTransferId: 82000000000000000002n,
  fundsReceivedTransferId: 83000000000000000001n,
  invoiceChargeTransferId: 83000000000000000002n,
};

function account(input: {
  id: bigint;
  ledger: number;
  code: number;
  flags: number;
  ownerId?: bigint;
  periodId?: bigint;
  unitOrCurrency?: number;
}): Account {
  return {
    id: input.id,
    debits_pending: 0n,
    debits_posted: 0n,
    credits_pending: 0n,
    credits_posted: 0n,
    user_data_128: input.ownerId ?? 0n,
    user_data_64: input.periodId ?? 0n,
    user_data_32: input.unitOrCurrency ?? 0,
    reserved: 0,
    ledger: input.ledger,
    code: input.code,
    flags: input.flags,
    timestamp: 0n,
  };
}

function transfer(input: {
  id: bigint;
  debitAccountId: bigint;
  creditAccountId: bigint;
  amount: bigint;
  ledger: number;
  code: number;
  ownerId?: bigint;
  periodId?: bigint;
  unitOrCurrency?: number;
}): Transfer {
  return {
    id: input.id,
    debit_account_id: input.debitAccountId,
    credit_account_id: input.creditAccountId,
    amount: input.amount,
    pending_id: 0n,
    user_data_128: input.ownerId ?? 0n,
    user_data_64: input.periodId ?? 0n,
    user_data_32: input.unitOrCurrency ?? 0,
    timeout: 0,
    ledger: input.ledger,
    code: input.code,
    flags: TransferFlags.none,
    timestamp: 0n,
  };
}

function sameAccount(actual: Account, expected: Account): boolean {
  return (
    actual.id === expected.id &&
    actual.ledger === expected.ledger &&
    actual.code === expected.code &&
    actual.flags === expected.flags &&
    actual.reserved === expected.reserved &&
    actual.user_data_128 === expected.user_data_128 &&
    actual.user_data_64 === expected.user_data_64 &&
    actual.user_data_32 === expected.user_data_32
  );
}

function sameTransfer(actual: Transfer, expected: Transfer): boolean {
  return (
    actual.id === expected.id &&
    actual.debit_account_id === expected.debit_account_id &&
    actual.credit_account_id === expected.credit_account_id &&
    actual.amount === expected.amount &&
    actual.pending_id === expected.pending_id &&
    actual.timeout === expected.timeout &&
    actual.ledger === expected.ledger &&
    actual.code === expected.code &&
    actual.flags === expected.flags &&
    actual.user_data_128 === expected.user_data_128 &&
    actual.user_data_64 === expected.user_data_64 &&
    actual.user_data_32 === expected.user_data_32
  );
}

async function ensureAccounts(client: Client, expected: Account[]): Promise<void> {
  let results: CreateAccountResult[] | CreateTransferResult[];
  try {
    results = await client.createAccounts(expected);
  } catch (error) {
    const actual = await client.lookupAccounts(expected.map((item) => item.id));
    const byId = new Map(actual.map((item) => [item.id, item]));
    const allMatch =
      actual.length === expected.length &&
      expected.every((item) => {
        const found = byId.get(item.id);
        return found !== undefined && sameAccount(found, item);
      });
    if (allMatch) return;
    throw error;
  }

  // Adapter omits gateway `persisted`; require exact post-write lookup always.
  const actual = await client.lookupAccounts(expected.map((item) => item.id));
  const byId = new Map(actual.map((item) => [item.id, item]));
  const mismatch = expected.find((item) => {
    const found = byId.get(item.id);
    return !found || !sameAccount(found, item);
  });
  if (!mismatch) return;
  if (results.length === 0) {
    throw new Error('Account write was not confirmed by lookup; do not advance or change the payload');
  }
  throw new Error(`createAccounts conflict at account ${mismatch.id}`);
}

async function transferAlreadyExists(client: Client, expected: Transfer): Promise<boolean> {
  const [actual] = await client.lookupTransfers([expected.id]);
  if (!actual) {
    return false;
  }
  if (!sameTransfer(actual, expected)) {
    throw new Error(`transfer ID ${expected.id} exists with different fields`);
  }
  return true;
}

async function createTransferWithLookup(client: Client, expected: Transfer): Promise<void> {
  // Every queue, scheduler, and webhook retry enters through this lookup.
  if (await transferAlreadyExists(client, expected)) {
    return;
  }

  try {
    const results = await client.createTransfers([expected]);
    // Adapter omits gateway `persisted`; confirm by exact lookup before advancing.
    if (await transferAlreadyExists(client, expected)) {
      return;
    }
    if (results.length === 0) {
      throw new Error('Transfer write was not confirmed by lookup; do not advance or change the payload');
    }
    throw new Error(
      `createTransfers rejected input 0 with result ${results[0]?.result ?? 'unknown'}` +
        (results[0]?.result === CreateTransferError.exceeds_credits ? ' (exceeds_credits)' : ''),
    );
  } catch (error) {
    // The HTTP response can be lost after acceptance. Never replace the ID.
    if (await transferAlreadyExists(client, expected)) {
      return;
    }
    throw error;
  }
}

async function run(client: Client): Promise<void> {
  await ensureAccounts(client, [
    account({
      id: persisted.grantSourceAccountId,
      ledger: USAGE_LEDGER,
      code: ACCOUNT_CODE.grantSource,
      flags: AccountFlags.history,
      unitOrCurrency: 1,
    }),
    account({
      id: persisted.subscriberAllowanceAccountId,
      ledger: USAGE_LEDGER,
      code: ACCOUNT_CODE.subscriberAllowance,
      flags: AccountFlags.history | AccountFlags.debits_must_not_exceed_credits,
      ownerId: persisted.subscriptionId,
      periodId: persisted.periodId,
      unitOrCurrency: 1,
    }),
    account({
      id: persisted.usageSinkAccountId,
      ledger: USAGE_LEDGER,
      code: ACCOUNT_CODE.usageSink,
      flags: AccountFlags.history,
      unitOrCurrency: 1,
    }),
    account({
      id: persisted.collectionSourceAccountId,
      ledger: MONEY_LEDGER,
      code: ACCOUNT_CODE.collectionSource,
      flags: AccountFlags.history,
      unitOrCurrency: 840,
    }),
    account({
      id: persisted.prepaidBalanceAccountId,
      ledger: MONEY_LEDGER,
      code: ACCOUNT_CODE.prepaidBalance,
      flags: AccountFlags.history | AccountFlags.debits_must_not_exceed_credits,
      ownerId: persisted.subscriptionId,
      unitOrCurrency: 840,
    }),
    account({
      id: persisted.billingClearingAccountId,
      ledger: MONEY_LEDGER,
      code: ACCOUNT_CODE.billingClearing,
      flags: AccountFlags.history,
      unitOrCurrency: 840,
    }),
  ]);

  await createTransferWithLookup(
    client,
    transfer({
      id: persisted.grantTransferId,
      debitAccountId: persisted.grantSourceAccountId,
      creditAccountId: persisted.subscriberAllowanceAccountId,
      amount: 100_000n,
      ledger: USAGE_LEDGER,
      code: TRANSFER_CODE.grant,
      ownerId: persisted.subscriptionId,
      periodId: persisted.periodId,
      unitOrCurrency: 1,
    }),
  );

  // usageTransferId is stored with sourceEventId and its assigned period.
  await createTransferWithLookup(
    client,
    transfer({
      id: persisted.usageTransferId,
      debitAccountId: persisted.subscriberAllowanceAccountId,
      creditAccountId: persisted.usageSinkAccountId,
      amount: 1_250n,
      ledger: USAGE_LEDGER,
      code: TRANSFER_CODE.consume,
      ownerId: persisted.subscriptionId,
      periodId: persisted.periodId,
      unitOrCurrency: 1,
    }),
  );

  const invoiceInput = await client.queryTransfers({
    user_data_128: persisted.subscriptionId,
    user_data_64: persisted.periodId,
    user_data_32: 1,
    ledger: USAGE_LEDGER,
    code: TRANSFER_CODE.consume,
    timestamp_min: 0n,
    timestamp_max: 0n,
    limit: 100,
    flags: QueryFilterFlags.none,
  });

  // The invoice service persists invoiceInput IDs, price-book version, and the
  // resulting amount. It does not derive cents inside the usage ledger.
  const persistedInvoiceAmountCents = 4_900n;

  // This event is written only after providerEventId has been verified and
  // durably deduplicated by the provider webhook receiver.
  await createTransferWithLookup(
    client,
    transfer({
      id: persisted.fundsReceivedTransferId,
      debitAccountId: persisted.collectionSourceAccountId,
      creditAccountId: persisted.prepaidBalanceAccountId,
      amount: persistedInvoiceAmountCents,
      ledger: MONEY_LEDGER,
      code: TRANSFER_CODE.fundsReceived,
      ownerId: persisted.subscriptionId,
      unitOrCurrency: 840,
    }),
  );

  await createTransferWithLookup(
    client,
    transfer({
      id: persisted.invoiceChargeTransferId,
      debitAccountId: persisted.prepaidBalanceAccountId,
      creditAccountId: persisted.billingClearingAccountId,
      amount: persistedInvoiceAmountCents,
      ledger: MONEY_LEDGER,
      code: TRANSFER_CODE.invoiceCharge,
      ownerId: persisted.subscriptionId,
      periodId: persisted.periodId,
      unitOrCurrency: 840,
    }),
  );

  console.log({
    sourceEventId: persisted.sourceEventId,
    providerEventId: persisted.providerEventId,
    invoiceId: persisted.invoiceId,
    invoiceInput,
  });
}

const baseUrl = process.env.PARIX_BASE_URL;
const apiKey = process.env.PARIX_API_KEY;
const databaseId = process.env.PARIX_DATABASE_ID;
if (!baseUrl || !apiKey || !databaseId) {
  throw new Error('PARIX_BASE_URL, PARIX_API_KEY, and PARIX_DATABASE_ID are required');
}

const client = createClient({ baseUrl, apiKey, databaseId });
try {
  await run(client);
} finally {
  client.destroy();
}