@hyperframes/aws-lambda 0.8.177 → 0.8.178

package/dist/_chunks/chunk-ON46F5DI.js

@@ -0,0 +1,589 @@
+import {
+  SITE_MANIFEST_INVALID,
+  downloadS3ObjectToFile,
+  ensureContentStoreObject,
+  formatExtension,
+  formatS3Uri,
+  isS3NotFound,
+  isSiteManifestUri,
+  mapConcurrent,
+  parseS3Uri,
+  parseSiteManifest,
+  putContentStoreFile,
+  s3ObjectExists,
+  serializeSiteManifest,
+  sha256File,
+  siteManifestUri,
+  siteTarballUri,
+  uploadContentAddressedFileToS3
+} from "./chunk-ZY5YIH5W.js";
+import {
+  CONTENT_STORE_RETENTION_DAYS
+} from "./chunk-YS3KY3C5.js";
+
+// src/sdk/deploySite.ts
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { S3Client } from "@aws-sdk/client-s3";
+import { hashProjectDir, listSiteFiles } from "@hyperframes/producer/distributed";
+function siteHandleFromId(bucketName, siteId) {
+  const projectS3Uri = siteManifestUri(bucketName, siteId);
+  return { siteId, bucketName, projectS3Uri, bytes: 0, uploadedAt: "", uploaded: false };
+}
+async function ensureSiteStored(site, s3, projectDir) {
+  if (!isSiteManifestUri(site.projectS3Uri)) return site;
+  const { bucket } = parseS3Uri(site.projectS3Uri);
+  const workdir = mkdtempSync(join(tmpdir(), "hf-site-check-"));
+  try {
+    const manifestPath = join(workdir, "files.json");
+    try {
+      await downloadS3ObjectToFile(s3, site.projectS3Uri, manifestPath);
+    } catch (error) {
+      if (!isS3NotFound(error)) throw error;
+      return await tarballSite(site, s3, bucket);
+    }
+    const files = parseSiteManifest(readFileSync(manifestPath, "utf-8"));
+    const missing = [];
+    await mapConcurrent(files, 16, async ({ path, sha256, sizeBytes }) => {
+      try {
+        await ensureContentStoreObject(s3, bucket, sha256, sizeBytes);
+      } catch (error) {
+        if (error.name !== "PLAN_ARTIFACT_MISSING") throw error;
+        if (!projectDir) return void missing.push(path);
+        await putContentStoreFile(s3, join(projectDir, path), bucket, sha256);
+      }
+    });
+    if (missing.length > 0) {
+      const error = new Error(
+        `[deploySite] SITE_FILES_MISSING: ${missing.length} of ${files.length} files of site ${site.siteId} are no longer stored (unused for ${CONTENT_STORE_RETENTION_DAYS} days). Run \`hyperframes lambda sites create\`, or pass projectDir to re-upload them.`
+      );
+      error.name = "SITE_FILES_MISSING";
+      throw error;
+    }
+    return site;
+  } finally {
+    rmSync(workdir, { recursive: true, force: true });
+  }
+}
+async function tarballSite(site, s3, bucket) {
+  const projectS3Uri = siteTarballUri(bucket, site.siteId);
+  if (await s3ObjectExists(s3, projectS3Uri)) return { ...site, projectS3Uri };
+  const error = new Error(
+    `[deploySite] SITE_NOT_FOUND: site ${site.siteId} has neither ${site.projectS3Uri} nor ${projectS3Uri}. Run \`hyperframes lambda sites create\` again and use the new site id.`
+  );
+  error.name = "SITE_NOT_FOUND";
+  throw error;
+}
+async function deploySite(opts) {
+  const s3 = opts.s3 ?? new S3Client({ region: opts.region });
+  if (!statSync(opts.projectDir).isDirectory()) {
+    throw new Error(`[deploySite] projectDir is not a directory: ${opts.projectDir}`);
+  }
+  const files = listSiteFiles(opts.projectDir);
+  const siteId = opts.siteId ?? hashProjectDir(opts.projectDir, files);
+  const projectS3Uri = siteManifestUri(opts.bucketName, siteId);
+  const stored = [];
+  let uploaded = false;
+  await mapConcurrent(files, 8, async (path) => {
+    const localPath = join(opts.projectDir, path);
+    const sha256 = await sha256File(localPath);
+    stored.push({ path, sha256, sizeBytes: statSync(localPath).size });
+    const outcome = await putContentStoreFile(s3, localPath, opts.bucketName, sha256);
+    uploaded ||= outcome === "uploaded";
+  });
+  stored.sort((a, b) => a.path < b.path ? -1 : 1);
+  const workdir = mkdtempSync(join(tmpdir(), "hf-deploy-site-"));
+  try {
+    const manifestPath = join(workdir, "files.json");
+    const manifest = serializeSiteManifest(stored);
+    writeFileSync(manifestPath, manifest);
+    const outcome = await uploadContentAddressedFileToS3(
+      s3,
+      manifestPath,
+      projectS3Uri,
+      await sha256File(manifestPath),
+      "application/json"
+    );
+    uploaded ||= outcome === "uploaded";
+  } finally {
+    rmSync(workdir, { recursive: true, force: true });
+  }
+  return {
+    siteId,
+    bucketName: opts.bucketName,
+    projectS3Uri,
+    bytes: stored.reduce((sum, file) => sum + file.sizeBytes, 0),
+    uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    uploaded
+  };
+}
+
+// src/sdk/validateConfig.ts
+import { InvalidConfigError } from "@hyperframes/producer/distributed";
+import {
+  InvalidConfigError as InvalidConfigError2,
+  validateDistributedRenderConfig,
+  validateVariablesPayload
+} from "@hyperframes/producer/distributed";
+var MAX_STEP_FUNCTIONS_INPUT_BYTES = 256 * 1024;
+var LARGE_VARIABLES_DOCS_URL = "https://hyperframes.heygen.com/deploy/templates-on-lambda#working-with-large-variables";
+function validateStepFunctionsInputSize(input) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(input);
+  } catch (err) {
+    throw new InvalidConfigError(
+      "config",
+      `Step Functions execution input is not JSON-serializable: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (serialized === void 0) {
+    throw new InvalidConfigError(
+      "config",
+      "Step Functions execution input is not JSON-serializable (JSON.stringify returned undefined). Check that all fields, including config.variables, are plain JSON values."
+    );
+  }
+  const byteLength = Buffer.byteLength(serialized, "utf8");
+  if (byteLength > MAX_STEP_FUNCTIONS_INPUT_BYTES) {
+    throw new InvalidConfigError(
+      "config",
+      `Step Functions execution input is ${byteLength} bytes, which exceeds the ${MAX_STEP_FUNCTIONS_INPUT_BYTES}-byte (256 KiB) limit for Standard workflows. Variables are for typed data (strings, numbers, structured records); media assets (images, audio, video) should be passed as URL references the composition resolves at render time, not inlined as base64. See ${LARGE_VARIABLES_DOCS_URL} for the URL-your-assets convention.`
+    );
+  }
+}
+
+// src/sdk/renderToLambda.ts
+import { randomUUID } from "node:crypto";
+import { DescribeStateMachineCommand, SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
+import { S3Client as S3Client2 } from "@aws-sdk/client-s3";
+async function renderToLambda(opts) {
+  validateDistributedRenderConfig(opts.config);
+  if (!opts.bucketName) {
+    throw new Error("[renderToLambda] bucketName is required");
+  }
+  if (!opts.stateMachineArn) {
+    throw new Error("[renderToLambda] stateMachineArn is required");
+  }
+  if (!opts.siteHandle && !opts.projectDir) {
+    throw new Error("[renderToLambda] either siteHandle or projectDir must be supplied");
+  }
+  const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
+  await assertStackReadsSites(sfn, opts.stateMachineArn);
+  const executionName = opts.executionName ?? `hf-render-${randomUUID()}`;
+  const ext = formatExtension(opts.config.format);
+  const outputKey = opts.outputKey ?? `renders/${executionName}/output${ext}`;
+  const planOutputS3Prefix = formatS3Uri({
+    bucket: opts.bucketName,
+    key: `renders/${executionName}/`
+  });
+  const outputS3Uri = formatS3Uri({ bucket: opts.bucketName, key: outputKey });
+  const site = opts.siteHandle ? await ensureSiteStored(
+    opts.siteHandle,
+    opts.s3 ?? new S3Client2({ region: opts.region }),
+    opts.projectDir
+  ) : await deploySite({
+    projectDir: opts.projectDir,
+    bucketName: opts.bucketName,
+    region: opts.region,
+    s3: opts.s3
+  });
+  const input = {
+    ProjectS3Uri: site.projectS3Uri,
+    PlanOutputS3Prefix: planOutputS3Prefix,
+    OutputS3Uri: outputS3Uri,
+    Config: opts.config,
+    PlanProtocol: opts.planProtocol ?? "v2"
+  };
+  validateStepFunctionsInputSize(input);
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const response = await sfn.send(
+    new StartExecutionCommand({
+      stateMachineArn: opts.stateMachineArn,
+      name: executionName,
+      input: JSON.stringify(input)
+    })
+  );
+  if (!response.executionArn) {
+    throw new Error("[renderToLambda] StartExecution returned no executionArn");
+  }
+  return {
+    renderId: executionName,
+    executionArn: response.executionArn,
+    bucketName: opts.bucketName,
+    stateMachineArn: opts.stateMachineArn,
+    outputS3Uri,
+    projectS3Uri: site.projectS3Uri,
+    startedAt
+  };
+}
+async function assertStackReadsSites(sfn, stateMachineArn) {
+  const { definition } = await sfn.send(new DescribeStateMachineCommand({ stateMachineArn }));
+  if (definition?.includes(`"${SITE_MANIFEST_INVALID}"`)) return;
+  const error = new Error(
+    `[renderToLambda] STACK_TOO_OLD: ${stateMachineArn} was deployed by an earlier @hyperframes/aws-lambda that cannot read this version's sites. Redeploy the stack first (\`hyperframes lambda deploy\`, or the SAM template / CDK construct from this version).`
+  );
+  error.name = "STACK_TOO_OLD";
+  throw error;
+}
+
+// src/sdk/costAccounting.ts
+var LAMBDA_USD_PER_GB_SECOND = 166667e-10;
+var SFN_USD_PER_TRANSITION = 25e-6;
+function computeRenderCost(lambdaInvocations, stateTransitions) {
+  let lambdaUsd = 0;
+  let anyEstimated = false;
+  for (const inv of lambdaInvocations) {
+    const gbSeconds = inv.memorySizeMb / 1024 * (inv.billedDurationMs / 1e3);
+    lambdaUsd += gbSeconds * LAMBDA_USD_PER_GB_SECOND;
+    if (inv.estimated) anyEstimated = true;
+  }
+  const stepFunctionsUsd = stateTransitions * SFN_USD_PER_TRANSITION;
+  const accruedSoFarUsd = roundUsd(lambdaUsd + stepFunctionsUsd);
+  return {
+    accruedSoFarUsd,
+    displayCost: formatUsd(accruedSoFarUsd),
+    breakdown: {
+      lambdaUsd: roundUsd(lambdaUsd),
+      stepFunctionsUsd: roundUsd(stepFunctionsUsd),
+      s3Estimate: "not-included",
+      estimated: anyEstimated
+    }
+  };
+}
+function roundUsd(usd) {
+  return Math.round(usd * 1e4) / 1e4;
+}
+function formatUsd(usd) {
+  return `$${usd.toFixed(4)}`;
+}
+
+// src/sdk/getRenderProgress.ts
+import {
+  DescribeExecutionCommand,
+  DescribeMapRunCommand,
+  GetExecutionHistoryCommand,
+  ListExecutionsCommand,
+  SFNClient as SFNClient2
+} from "@aws-sdk/client-sfn";
+var DEFAULT_MEMORY_MB = 10240;
+function createProgressSfnClient(config = {}) {
+  return new SFNClient2({ maxAttempts: 8, ...config });
+}
+async function getRenderProgress(opts) {
+  if (!opts.executionArn) {
+    throw new Error("[getRenderProgress] executionArn is required");
+  }
+  const sfn = opts.sfn ?? createProgressSfnClient({ region: opts.region });
+  const memoryMb = opts.defaultMemorySizeMb ?? DEFAULT_MEMORY_MB;
+  const describe = await sfn.send(
+    new DescribeExecutionCommand({ executionArn: opts.executionArn })
+  );
+  const status = describe.status ?? "RUNNING";
+  const startedAt = describe.startDate?.toISOString() ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const endedAt = describe.stopDate?.toISOString() ?? null;
+  const history = await loadFullHistory(sfn, opts.executionArn);
+  const summary = summarizeHistory(history, memoryMb);
+  const mapRun = findChunkMapRun(history);
+  const warnings = [];
+  if (mapRun?.exited) addChunkResults(summary, mapRun.output, memoryMb);
+  else if (mapRun) {
+    await addRunningMapRun(sfn, mapRun.arn, summary, memoryMb).catch((err) => {
+      if (err?.name !== "AccessDeniedException") throw err;
+      warnings.push(MAP_RUN_ACCESS_DENIED);
+    });
+  }
+  const costs = computeRenderCost(summary.lambdaInvocations, summary.stateTransitions);
+  const overallProgress = computeOverallProgress({
+    status,
+    totalFrames: summary.totalFrames,
+    framesRendered: summary.framesRendered,
+    assembleComplete: summary.assembleComplete
+  });
+  return {
+    status,
+    overallProgress,
+    framesRendered: summary.framesRendered,
+    totalFrames: summary.totalFrames,
+    lambdasInvoked: summary.lambdasInvoked,
+    costs,
+    outputFile: summary.outputFile,
+    errors: summary.errors,
+    fatalErrorEncountered: isTerminalFailure(status),
+    warnings,
+    startedAt,
+    endedAt
+  };
+}
+async function loadFullHistory(sfn, executionArn) {
+  const events = [];
+  let nextToken;
+  for (let page = 0; page < 50; page++) {
+    const res = await sfn.send(
+      new GetExecutionHistoryCommand({
+        executionArn,
+        maxResults: 1e3,
+        nextToken,
+        reverseOrder: false
+      })
+    );
+    if (res.events) events.push(...res.events);
+    nextToken = res.nextToken;
+    if (!nextToken) break;
+  }
+  return events;
+}
+var FAILED_CHUNK_HISTORIES_READ = 5;
+var MAP_RUN_ACCESS_DENIED = "Chunk progress is hidden until the chunks finish: this caller lacks states:DescribeMapRun. Re-apply the policy from `hyperframes lambda policies user`.";
+function findChunkMapRun(events) {
+  let run = null;
+  for (const ev of events) {
+    const arn = ev.mapRunStartedEventDetails?.mapRunArn;
+    if (arn) run = { arn, exited: false, output: void 0 };
+    const exit = ev.stateExitedEventDetails;
+    if (run && ev.type === "MapStateExited" && isRenderChunksMapState(exit?.name)) {
+      run = { ...run, exited: true, output: exit?.output };
+    }
+  }
+  return run;
+}
+function addChunkResults(summary, mapOutput, memoryMb) {
+  const chunks = parseJson(mapOutput)?.Chunks;
+  for (const chunk of Array.isArray(chunks) ? chunks : []) {
+    summary.lambdasInvoked++;
+    summary.stateTransitions++;
+    const billedDurationMs = inferBilledMs(chunk);
+    summary.lambdaInvocations.push({
+      billedDurationMs,
+      memorySizeMb: memoryMb,
+      estimated: billedDurationMs === 0
+    });
+    applyPayloadFrameCounts(chunk, "RenderChunk", (delta) => {
+      summary.framesRendered += delta;
+    });
+  }
+}
+async function addRunningMapRun(sfn, mapRunArn, summary, memoryMb) {
+  const res = await sfn.send(new DescribeMapRunCommand({ mapRunArn }));
+  const { total = 0, pending = 0, succeeded = 0, failed = 0 } = res.itemCounts ?? {};
+  summary.lambdasInvoked += total - pending;
+  summary.stateTransitions += total - pending;
+  if (summary.totalFrames !== null && total > 0) {
+    summary.framesRendered += Math.floor(summary.totalFrames * succeeded / total);
+  }
+  if (failed > 0) summary.errors.push(...await failedChunkErrors(sfn, mapRunArn, memoryMb));
+}
+async function failedChunkErrors(sfn, mapRunArn, memoryMb) {
+  const failed = await sfn.send(
+    new ListExecutionsCommand({
+      mapRunArn,
+      statusFilter: "FAILED",
+      maxResults: FAILED_CHUNK_HISTORIES_READ
+    })
+  );
+  const errors = [];
+  for (const child of failed.executions ?? []) {
+    if (!child.executionArn) continue;
+    const childHistory = await loadFullHistory(sfn, child.executionArn);
+    errors.push(...summarizeHistory(childHistory, memoryMb).errors);
+  }
+  return errors;
+}
+function summarizeHistory(events, memoryMb) {
+  let framesRendered = 0;
+  let totalFrames = null;
+  let lambdasInvoked = 0;
+  let assembleComplete = false;
+  let outputFile = null;
+  let stateTransitions = 0;
+  const errors = [];
+  const lambdaInvocations = [];
+  let currentLambdaState = null;
+  for (const ev of events) {
+    switch (ev.type) {
+      case "TaskStateEntered":
+      case "MapStateEntered":
+      case "PassStateEntered":
+      case "ChoiceStateEntered":
+      case "SucceedStateEntered":
+      case "FailStateEntered":
+      case "WaitStateEntered":
+      case "ParallelStateEntered":
+        stateTransitions++;
+        currentLambdaState = ev.stateEnteredEventDetails?.name ?? currentLambdaState;
+        break;
+      // Optimized `lambda:invoke` task emits Task* events; raw
+      // `lambda:invokeFunction.sync` emits LambdaFunction*. Handle both.
+      case "TaskScheduled":
+        if (ev.taskScheduledEventDetails?.resourceType === "lambda") {
+          lambdasInvoked++;
+        }
+        break;
+      case "LambdaFunctionScheduled":
+        lambdasInvoked++;
+        break;
+      case "TaskSucceeded": {
+        if (ev.taskSucceededEventDetails?.resourceType !== "lambda") break;
+        const wrapped = parseJson(ev.taskSucceededEventDetails?.output);
+        const payload = unwrapLambdaPayload(wrapped);
+        const billedDurationMs = inferBilledMs(payload);
+        lambdaInvocations.push({
+          billedDurationMs,
+          memorySizeMb: memoryMb,
+          estimated: billedDurationMs === 0
+        });
+        applyPayloadFrameCounts(payload, currentLambdaState, (delta) => {
+          framesRendered += delta;
+        });
+        if (payload && typeof payload === "object") {
+          const obj = payload;
+          if (typeof obj.TotalFrames === "number") totalFrames = obj.TotalFrames;
+        }
+        break;
+      }
+      case "LambdaFunctionSucceeded": {
+        const payload = parseJson(ev.lambdaFunctionSucceededEventDetails?.output);
+        const billedDurationMs = inferBilledMs(payload);
+        lambdaInvocations.push({
+          billedDurationMs,
+          memorySizeMb: memoryMb,
+          estimated: billedDurationMs === 0
+        });
+        applyPayloadFrameCounts(payload, currentLambdaState, (delta) => {
+          framesRendered += delta;
+        });
+        if (payload && typeof payload === "object") {
+          const obj = payload;
+          if (typeof obj.TotalFrames === "number") totalFrames = obj.TotalFrames;
+        }
+        break;
+      }
+      case "TaskStateExited":
+      case "MapStateExited":
+        if (isAssembleState(ev.stateExitedEventDetails?.name)) {
+          assembleComplete = true;
+          const exitPayload = parseJson(ev.stateExitedEventDetails?.output);
+          if (exitPayload && typeof exitPayload === "object") {
+            const obj = exitPayload;
+            const out = obj.Output;
+            const outputS3Uri = typeof out?.OutputS3Uri === "string" ? out.OutputS3Uri : null;
+            const bytes = typeof out?.FileSize === "number" ? out.FileSize : null;
+            outputFile = outputS3Uri ? { s3Uri: outputS3Uri, bytes } : outputFile;
+          }
+        }
+        break;
+      case "TaskFailed":
+        if (ev.taskFailedEventDetails?.resourceType !== "lambda") break;
+        errors.push({
+          state: currentLambdaState ?? "<unknown>",
+          error: ev.taskFailedEventDetails?.error ?? "UNKNOWN",
+          cause: ev.taskFailedEventDetails?.cause ?? ""
+        });
+        break;
+      case "LambdaFunctionFailed":
+        errors.push({
+          state: currentLambdaState ?? "<unknown>",
+          error: ev.lambdaFunctionFailedEventDetails?.error ?? "UNKNOWN",
+          cause: ev.lambdaFunctionFailedEventDetails?.cause ?? ""
+        });
+        break;
+      case "ExecutionFailed":
+        errors.push({
+          state: "<execution>",
+          error: ev.executionFailedEventDetails?.error ?? "UNKNOWN",
+          cause: ev.executionFailedEventDetails?.cause ?? ""
+        });
+        break;
+      case "ExecutionAborted":
+        errors.push({
+          state: "<execution>",
+          error: ev.executionAbortedEventDetails?.error ?? "ABORTED",
+          cause: ev.executionAbortedEventDetails?.cause ?? ""
+        });
+        break;
+      case "ExecutionTimedOut":
+        errors.push({
+          state: "<execution>",
+          error: "TIMEOUT",
+          cause: ev.executionTimedOutEventDetails?.cause ?? ""
+        });
+        break;
+      default:
+        break;
+    }
+  }
+  return {
+    lambdaInvocations,
+    stateTransitions,
+    framesRendered,
+    totalFrames,
+    lambdasInvoked,
+    assembleComplete,
+    outputFile,
+    errors
+  };
+}
+function parseJson(s) {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+function unwrapLambdaPayload(payload) {
+  if (payload && typeof payload === "object" && "Payload" in payload) {
+    const inner = payload.Payload;
+    if (inner && typeof inner === "object") return inner;
+  }
+  return payload;
+}
+function applyPayloadFrameCounts(payload, currentLambdaState, bump) {
+  if (!isRenderChunkState(currentLambdaState)) return;
+  if (!payload || typeof payload !== "object") return;
+  const obj = payload;
+  if (typeof obj.FramesEncoded === "number") bump(obj.FramesEncoded);
+}
+function isRenderChunkState(name) {
+  return name === "RenderChunk" || name === "RenderChunkV2";
+}
+function isRenderChunksMapState(name) {
+  return name === "RenderChunks" || name === "RenderChunksV2";
+}
+function isAssembleState(name) {
+  return name === "Assemble" || name === "AssembleV2";
+}
+function inferBilledMs(payload) {
+  if (!payload || typeof payload !== "object") return 0;
+  const obj = payload;
+  if (typeof obj.DurationMs === "number") return obj.DurationMs;
+  return 0;
+}
+function computeOverallProgress({
+  status,
+  totalFrames,
+  framesRendered,
+  assembleComplete
+}) {
+  if (status === "SUCCEEDED") return 1;
+  if (assembleComplete) return 1;
+  if (totalFrames === null) return 0;
+  const chunkProgress = Math.min(1, framesRendered / totalFrames);
+  return 0.1 + 0.8 * chunkProgress;
+}
+function isTerminalFailure(status) {
+  return status === "FAILED" || status === "TIMED_OUT" || status === "ABORTED";
+}
+
+export {
+  siteHandleFromId,
+  deploySite,
+  MAX_STEP_FUNCTIONS_INPUT_BYTES,
+  validateStepFunctionsInputSize,
+  InvalidConfigError2 as InvalidConfigError,
+  validateDistributedRenderConfig,
+  validateVariablesPayload,
+  renderToLambda,
+  computeRenderCost,
+  getRenderProgress
+};

package/dist/_chunks/chunk-YS3KY3C5.js

@@ -0,0 +1,19 @@
+// src/contentStore.ts
+var CONTENT_STORE_PREFIX = "cas/sha256";
+var CONTENT_STORE_RETENTION_DAYS = 30;
+var CONTENT_STORE_REFRESH_AFTER_DAYS = 7;
+function contentStoreUri(bucket, sha256) {
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw new Error(
+      `[contentStore] expected lowercase SHA-256 digest, got ${JSON.stringify(sha256)}`
+    );
+  }
+  return `s3://${bucket}/${CONTENT_STORE_PREFIX}/${sha256.slice(0, 2)}/${sha256}`;
+}
+
+export {
+  CONTENT_STORE_PREFIX,
+  CONTENT_STORE_RETENTION_DAYS,
+  CONTENT_STORE_REFRESH_AFTER_DAYS,
+  contentStoreUri
+};