Storage

const folder = await storage.ensureFolderPath('imports/bank/daily', {
  restricted: true,
  groups: [api.input('financeGroupId')],
});

// Relative lifetime, counted from successful finalization.
{ retention: { ttlSeconds: 7 * 24 * 60 * 60 } }

// Absolute future instant.
{ retention: { expiresAt: '2026-12-31T23:59:59.000Z' } }

// Explicitly no expiration.
{ retention: null }

const current = await storage.getEntry(api.input('storageEntryId'));

const renamed = await storage.updateEntry(current.storageEntryId, {
  version: current.version,
  name: 'transactions-validated.csv',
  metadata: {
    documentType: 'transaction-import',
    processingState: 'validated',
  },
});

const folder = await storage.ensureFolderPath('exports/reconciliation');
const { session } = await storage.createUploadSession({
  parentStorageEntryId: folder.storageEntryId,
  name: `reconciliation-${api.getOperationId()}.csv`,
  contentTypeHint: 'text/csv',
  uploadMode: 'incremental',
  computeStats: 'sync',
  retention: { ttlSeconds: 30 * 24 * 60 * 60 },
  metadata: { documentType: 'reconciliation-result' },
});

try {
  await storage.uploadPart(session.storageUploadSessionId, {
    data: 'transactionId,status\n',
    dataEncoding: 'utf8',
  });
  await storage.uploadPart(session.storageUploadSessionId, {
    data: ['txn_1001,accepted\n', 'txn_1002,rejected\n'],
    dataEncoding: 'utf8',
  });

  const finalized = await storage.finalizeUploadSession(
    session.storageUploadSessionId,
    { computeStats: 'sync' },
  );
  return { storageEntryId: finalized.entry.storageEntryId };
} catch (error) {
  await storage.abortUploadSession(session.storageUploadSessionId).catch(() => undefined);
  throw error;
}

const storageEntryId = api.input('storageEntryId');
const stats = await storage.getFileStats(storageEntryId);

for (let batchNumber = 1; batchNumber <= (stats.batches ?? 0); batchNumber += 1) {
  const lines = await storage.getFileData(storageEntryId, { batchNumber });
  // Validate and persist one bounded batch before reading the next one.
}

const excerpt = await storage.getText(api.input('storageEntryId'), {
  startLine: 1,
  endLine: 200,
  maxChars: 8_000,
});

return {
  content: excerpt.content,
  totalLines: excerpt.totalLines,
  truncated: excerpt.truncated,
};

RESERVED -> UPLOADING -> FINALIZING -> FINALIZED
                  |             |
                  +-> ABORTED    +-> FAILED
                  +-> EXPIRED

const event = api.input();
const operationId = api.getOperationId();
const sourceId = event?.message?.storageEntryId;

if (event?.type !== 'STORAGE_CREATED' || typeof sourceId !== 'string') {
  api.throw(400, { message: 'Expected a STORAGE_CREATED input', operationId });
}

const source = await storage.getFile(sourceId);
const sourceVersion = source.version;
const stats = await storage.getFileStats(source.storageEntryId);
let accepted = 0;
let rejected = 0;

for (let batchNumber = 1; batchNumber <= (stats.batches ?? 0); batchNumber += 1) {
  const lines = await storage.getFileData(source.storageEntryId, { batchNumber });
  for (const line of lines) {
    // Replace this bounded validation with your domain parser.
    line.includes(',') ? accepted += 1 : rejected += 1;
  }
}

const outputFolder = await storage.resolveFolderPath('imports/bank/processed');
const output = await storage.putObject({
  parentStorageEntryId: outputFolder.storageEntryId,
  name: `result-${source.storageEntryId}-v${sourceVersion}.json`,
  data: JSON.stringify({
    operationId,
    sourceStorageEntryId: source.storageEntryId,
    sourceVersion,
    accepted,
    rejected,
  }, null, 2),
  mimeType: 'application/json',
  computeStats: 'sync',
  retention: { ttlSeconds: 90 * 24 * 60 * 60 },
  metadata: {
    documentType: 'bank-transaction-result',
    sourceStorageEntryId: source.storageEntryId,
    sourceVersion,
    operationId,
  },
});

api.log({
  message: 'Storage import processed',
  args: {
    operationId,
    sourceStorageEntryId: source.storageEntryId,
    sourceVersion,
    outputStorageEntryId: output.storageEntryId,
    accepted,
    rejected,
  },
}, 'INFO');

return {
  operationId,
  sourceStorageEntryId: source.storageEntryId,
  outputStorageEntryId: output.storageEntryId,
  accepted,
  rejected,
};