feat: use latest snapshot fallback for daily billing migration

Author: BravoNatalie

billing/data/space-snapshot.js

@@ -65,3 +65,13 @@ export const decode = input => {
     }
   }
 }
+
+export const lister = {
+  /** @type {import('../lib/api.js').Encoder<Pick<SpaceSnapshotKey, 'provider'|'space'>, Pick<SpaceSnapshotKeyStoreRecord, 'pk'>>} */
+  encodeKey: (input) => ({
+    ok: {
+      pk: `${input.provider}#${input.space}`
+    }
+  })
+}
+

billing/functions/usage-table.js

@@ -256,10 +256,11 @@ export const reportUsage = async (usage, ctx) => {
   const cumulativeByteQuantity = Math.floor(new Big(usage.usage.toString()).div(duration).toNumber())
 
   const isFirstOfMonth = usage.from.getUTCDate() === 1
+  const isFirstDailyRun = usage.from <= new Date('2026-02-25T00:00:00.000Z')  // Hardcoded migration cutoff. TODO: remove it after 
   // NOTE: Since Stripe aggregates per billing period (monthly), each month starts fresh so no need to get previous usage and calculate delta.
   let previousCumulativeUsage                                                                                                
   try {                                                                                                                      
-    previousCumulativeUsage = isFirstOfMonth ? 0n : await getPreviousUsage(usage, ctx)                                       
+    previousCumulativeUsage = (isFirstOfMonth || isFirstDailyRun) ? 0n : await getPreviousUsage(usage, ctx)                                       
   } catch (/** @type {any} */ err) {                                                                                         
     return { error: err }                                                                                                    
   } 

billing/lib/api.ts

@@ -72,6 +72,7 @@ export interface SpaceSnapshotKey { provider: ProviderDID, space: ConsumerDID, r
 export type SpaceSnapshotStore =
   & StorePutter<SpaceSnapshot>
   & StoreGetter<SpaceSnapshotKey, SpaceSnapshot>
+  & StoreLister<Pick<SpaceSnapshotKey, 'provider'|'space'>, SpaceSnapshot>
 
 /**
  * Captures information about a customer of the service that may need to be
@@ -455,7 +456,7 @@ export interface StoreGetter<K extends {}, V> {
 /** StoreLister allows items in the store to be listed page by page. */
 export interface StoreLister<K extends {}, V> {
   /** Lists items in the store. */
-  list: (key: K, options?: Pageable) => Promise<Result<ListSuccess<V>, EncodeFailure|DecodeFailure|StoreOperationFailure>>
+  list: (key: K, options?: Pageable & { scanIndexForward?: boolean }) => Promise<Result<ListSuccess<V>, EncodeFailure|DecodeFailure|StoreOperationFailure>>
 }
 
 /** QueueAdder allows messages to be added to the end of the queue. */

billing/lib/space-billing-queue.js

@@ -56,21 +56,47 @@ export const calculatePeriodUsage = async (instruction, ctx) => {
   console.log(`Customer: ${instruction.customer}`)
   console.log(`Period: ${instruction.from.toISOString()} - ${instruction.to.toISOString()}`)
 
+  // Try to get snapshot at exact 'from' date first
   const { ok: snap, error } = await ctx.spaceSnapshotStore.get({
     space: instruction.space,
     provider: instruction.provider,
     recordedAt: instruction.from
   })
   if (error && error.name !== 'RecordNotFound') return { error }
-  if (!snap) console.warn(`!!! Snapshot not found, assuming empty space !!!`)
 
-  let size = snap?.size ?? 0n
-  let usage = size * BigInt(instruction.to.getTime() - instruction.from.getTime()) // initial usage from snapshot
+  let snapshotToUse = snap
+  let snapshotDate = instruction.from
+
+  // If no snapshot at exact 'from' date, list snapshots in descending order (newest first)
+  // and check if the most recent one is before 'from'.
+  if (!snap) {
+    console.warn(`No snapshot found at ${instruction.from.toISOString()}, querying for most recent snapshot before this date...`)
+
+    const listResult = await ctx.spaceSnapshotStore.list({
+      space: instruction.space,
+      provider: instruction.provider
+    }, { size: 1, scanIndexForward: false }) // get newest snapshot
+
+    if (listResult.error) return listResult
+
+    // Check if the newest snapshot is at or before 'from'
+    const newestSnapshot = listResult.ok.results[0]
+    if (newestSnapshot && newestSnapshot.recordedAt.getTime() <= instruction.from.getTime()) {
+      snapshotToUse = newestSnapshot
+      snapshotDate = newestSnapshot.recordedAt
+      console.log(`Found snapshot @ ${snapshotDate.toISOString()}: ${newestSnapshot.size} bytes`)
+    } else {
+      console.warn(`!!! No snapshot found before ${instruction.from.toISOString()}, assuming empty space !!!`)
+    }
+  }
+
+  let size = snapshotToUse ? snapshotToUse.size : 0n
+  let usage = size * BigInt(instruction.to.getTime() - snapshotDate.getTime()) // initial usage from snapshot
 
-  console.log(`Total size of ${instruction.space} is ${size} bytes @ ${instruction.from.toISOString()}`)
+  console.log(`Starting calculation from ${snapshotDate.toISOString()}: ${size} bytes for ${instruction.space}`)
 
   let totalDiffs = 0
-  for await (const page of iterateSpaceDiffs(instruction, ctx)) {
+  for await (const page of iterateSpaceDiffs({...instruction, from: snapshotDate}, ctx)) {
     if (page.error) return page
     totalDiffs += page.ok.length
     for (const diff of page.ok) {

billing/tables/client.js

@@ -182,6 +182,7 @@ export const createStoreListerClient = (conf, context) => {
           IndexName: context.indexName,
           Limit: options?.size ?? 100,
           KeyConditions: conditions,
+          ScanIndexForward: options?.scanIndexForward,
           ExclusiveStartKey: options?.cursor
             ? marshall(JSON.parse(options.cursor))
             : undefined

billing/tables/space-snapshot.js

@@ -1,5 +1,5 @@
-import { createStoreGetterClient, createStorePutterClient } from './client.js'
-import { validate, encode, decode, encodeKey } from '../data/space-snapshot.js'
+import { createStoreGetterClient, createStoreListerClient, createStorePutterClient } from './client.js'
+import { validate, encode, decode, encodeKey, lister } from '../data/space-snapshot.js'
 
 /**
  * Stores snapshots of total space size at a given time.
@@ -35,5 +35,6 @@ export const spaceSnapshotTableProps = {
  */
 export const createSpaceSnapshotStore = (conf, { tableName }) => ({
   ...createStorePutterClient(conf, { tableName, validate, encode }),
-  ...createStoreGetterClient(conf, { tableName, encodeKey, decode })
+  ...createStoreGetterClient(conf, { tableName, encodeKey, decode }),
+  ...createStoreListerClient(conf, { tableName, encodeKey: lister.encodeKey, decode })
 })