@ericminassian/platform 0.0.0-stage → 0.1.0

package/src/db.ts

@@ -0,0 +1,380 @@
+import {
+  DeleteCommand,
+  type DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  QueryCommand,
+  type QueryCommandInput,
+  UpdateCommand,
+} from '@aws-sdk/lib-dynamodb';
+import { getBindings } from './bindings.ts';
+import { ddbClient } from './clients.ts';
+import { span } from './telemetry.ts';
+
+/**
+ * Document collections on the stage's single DynamoDB table (single-table
+ * design). Adding a collection needs no provisioning.
+ *
+ * Item layout:
+ *   pk       = "<collection>#<partition values joined by #>"
+ *   sk       = "<sort values joined by #>"  (or "#" without a sort key)
+ *   gsi{n}pk = "<collection>#<index>#<values>", gsi{n}sk = sort values or "#"
+ *   _c       = collection, _ttl = epoch seconds (DynamoDB TTL)
+ * Internal attributes are stripped from everything returned.
+ */
+
+export type KeyValue = string | number;
+
+type Fields<T> = (keyof T & string) | readonly (keyof T & string)[];
+
+export interface CollectionOptions<T> {
+  /** Attribute(s) forming the partition key. */
+  partition: Fields<T>;
+  /** Attribute(s) forming the sort key (optional). */
+  sort?: Fields<T>;
+  /** Up to three secondary indexes, each pinned to a fixed slot so reordering is safe. */
+  indexes?: Record<string, { slot: 1 | 2 | 3; partition: Fields<T>; sort?: Fields<T> }>;
+  /** Attribute holding an epoch-seconds expiry (DynamoDB TTL). */
+  ttl?: keyof T & string;
+}
+
+export interface QueryOptions {
+  index?: string;
+  beginsWith?: string;
+  between?: [KeyValue, KeyValue];
+  gt?: KeyValue;
+  gte?: KeyValue;
+  lt?: KeyValue;
+  lte?: KeyValue;
+  limit?: number;
+  cursor?: string;
+  reverse?: boolean;
+}
+
+export interface Page<T> {
+  items: T[];
+  cursor?: string;
+}
+
+export interface Collection<T extends Record<string, unknown>> {
+  get(key: Partial<T>): Promise<T | undefined>;
+  put(item: T, opts?: { ifNotExists?: boolean }): Promise<T>;
+  update(key: Partial<T>, patch: Partial<T>): Promise<T>;
+  delete(key: Partial<T>): Promise<void>;
+  /** All items sharing the given partition-key values. */
+  query(partition: Partial<T>, opts?: QueryOptions): Promise<Page<T>>;
+}
+
+export interface Db {
+  collection<T extends Record<string, unknown>>(name: string, opts: CollectionOptions<T>): Collection<T>;
+  /** Escape hatch (AWS-specific): the DynamoDB document client and table name. */
+  raw(): { client: unknown; table: string };
+}
+
+export const INTERNAL_ATTRIBUTES = [
+  'pk',
+  'sk',
+  'gsi1pk',
+  'gsi1sk',
+  'gsi2pk',
+  'gsi2sk',
+  'gsi3pk',
+  'gsi3sk',
+  '_c',
+  '_ttl',
+];
+const COLLECTION_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+function list<T>(f: Fields<T> | undefined): string[] {
+  if (!f) return [];
+  return typeof f === 'string' ? [f] : [...f];
+}
+
+function table(): string {
+  const t = getBindings().table;
+  if (!t) throw new Error('This app has no database. Add `"db": true` to platform.json.');
+  return t;
+}
+
+function ddb(): DynamoDBDocumentClient {
+  return ddbClient();
+}
+
+/** Values for `fields` from `item`, joined by `#`. Throws when any is missing. */
+export function keyPart(item: Record<string, unknown>, fields: string[], what: string): string {
+  return fields
+    .map((f) => {
+      const v = item[f];
+      if (v === undefined || v === null || v === '') throw new Error(`${what}: missing key attribute "${f}"`);
+      if (typeof v !== 'string' && typeof v !== 'number')
+        throw new Error(`${what}: key attribute "${f}" must be a string or number`);
+      return String(v);
+    })
+    .join('#');
+}
+
+function hasAll(item: Record<string, unknown>, fields: string[]): boolean {
+  return fields.every((f) => item[f] !== undefined && item[f] !== null && item[f] !== '');
+}
+
+export function stripInternal<T>(item: Record<string, unknown> | undefined): T | undefined {
+  if (!item) return undefined;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(item)) if (!INTERNAL_ATTRIBUTES.includes(k)) out[k] = v;
+  return out as T;
+}
+
+export function encodeCursor(key: Record<string, unknown> | undefined): string | undefined {
+  return key ? Buffer.from(JSON.stringify(key)).toString('base64url') : undefined;
+}
+
+export function decodeCursor(cursor: string | undefined): Record<string, unknown> | undefined {
+  if (!cursor) return undefined;
+  try {
+    return JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+  } catch {
+    throw new Error('Invalid cursor');
+  }
+}
+
+/** Pure key/attribute mapping, exported for tests and the console's data browser. */
+export function createKeyMapper<T extends Record<string, unknown>>(name: string, opts: CollectionOptions<T>) {
+  if (!COLLECTION_NAME.test(name)) throw new Error(`Invalid collection name "${name}"`);
+  const partition = list(opts.partition);
+  const sort = list(opts.sort);
+  if (partition.length === 0) throw new Error(`Collection "${name}" needs a partition key`);
+  const indexes = Object.entries(opts.indexes ?? {}).map(([indexName, ix]) => ({
+    name: indexName,
+    slot: ix.slot,
+    partition: list(ix.partition),
+    sort: list(ix.sort),
+  }));
+  const slots = new Set<number>();
+  for (const ix of indexes) {
+    if (slots.has(ix.slot)) throw new Error(`Collection "${name}": two indexes use slot ${ix.slot}`);
+    slots.add(ix.slot);
+  }
+  const what = `collection "${name}"`;
+
+  const primaryKey = (item: Record<string, unknown>) => ({
+    pk: `${name}#${keyPart(item, partition, what)}`,
+    sk: sort.length ? keyPart(item, sort, what) : '#',
+  });
+
+  /** gsi/ttl attributes for `item`; `null` values mean "remove". */
+  const derived = (item: Record<string, unknown>): Record<string, string | number | null> => {
+    const out: Record<string, string | number | null> = {};
+    for (const ix of indexes) {
+      if (hasAll(item, ix.partition) && (ix.sort.length === 0 || hasAll(item, ix.sort))) {
+        out[`gsi${ix.slot}pk`] = `${name}#${ix.name}#${keyPart(item, ix.partition, what)}`;
+        out[`gsi${ix.slot}sk`] = ix.sort.length ? keyPart(item, ix.sort, what) : '#';
+      } else {
+        out[`gsi${ix.slot}pk`] = null;
+        out[`gsi${ix.slot}sk`] = null;
+      }
+    }
+    if (opts.ttl) {
+      const v = item[opts.ttl];
+      out._ttl = typeof v === 'number' ? Math.floor(v) : null;
+    }
+    return out;
+  };
+
+  const toItem = (item: T): Record<string, unknown> => {
+    const extra: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(derived(item))) if (v !== null) extra[k] = v;
+    return { ...item, ...primaryKey(item), _c: name, ...extra };
+  };
+
+  const queryInput = (values: Partial<T>, q: QueryOptions, tableName: string): QueryCommandInput => {
+    let pkAttr = 'pk';
+    let skAttr = 'sk';
+    let pkValue: string;
+    let indexName: string | undefined;
+    if (q.index) {
+      const ix = indexes.find((i) => i.name === q.index);
+      if (!ix) throw new Error(`${what} has no index "${q.index}"`);
+      pkAttr = `gsi${ix.slot}pk`;
+      skAttr = `gsi${ix.slot}sk`;
+      indexName = `gsi${ix.slot}`;
+      pkValue = `${name}#${ix.name}#${keyPart(values, ix.partition, what)}`;
+    } else {
+      pkValue = `${name}#${keyPart(values, partition, what)}`;
+    }
+    const names: Record<string, string> = { '#pk': pkAttr };
+    const vals: Record<string, unknown> = { ':pk': pkValue };
+    let cond = '#pk = :pk';
+    const sortCond = (expr: string) => {
+      names['#sk'] = skAttr;
+      cond += ` AND ${expr}`;
+    };
+    if (q.beginsWith !== undefined) {
+      vals[':b'] = String(q.beginsWith);
+      sortCond('begins_with(#sk, :b)');
+    } else if (q.between) {
+      vals[':lo'] = String(q.between[0]);
+      vals[':hi'] = String(q.between[1]);
+      sortCond('#sk BETWEEN :lo AND :hi');
+    } else {
+      const ops: Array<[keyof QueryOptions, string]> = [
+        ['gt', '>'],
+        ['gte', '>='],
+        ['lt', '<'],
+        ['lte', '<='],
+      ];
+      const set = ops.filter(([k]) => q[k] !== undefined);
+      if (set.length > 1) throw new Error('Use `between` for a range; only one of gt/gte/lt/lte is allowed');
+      const op = set[0];
+      if (op) {
+        vals[':v'] = String(q[op[0]]);
+        sortCond(`#sk ${op[1]} :v`);
+      }
+    }
+    const start = decodeCursor(q.cursor);
+    return {
+      TableName: tableName,
+      ...(indexName ? { IndexName: indexName } : {}),
+      KeyConditionExpression: cond,
+      ExpressionAttributeNames: names,
+      ExpressionAttributeValues: vals,
+      ScanIndexForward: !q.reverse,
+      ...(q.limit ? { Limit: q.limit } : {}),
+      ...(start ? { ExclusiveStartKey: start } : {}),
+    };
+  };
+
+  const keyFields = new Set([...partition, ...sort]);
+  const derivedSources = new Set([
+    ...indexes.flatMap((i) => [...i.partition, ...i.sort]),
+    ...(opts.ttl ? [opts.ttl] : []),
+  ]);
+
+  return {
+    name,
+    partition,
+    sort,
+    indexes,
+    primaryKey,
+    derived,
+    toItem,
+    queryInput,
+    keyFields,
+    derivedSources,
+  };
+}
+
+function collection<T extends Record<string, unknown>>(
+  name: string,
+  opts: CollectionOptions<T>,
+): Collection<T> {
+  const m = createKeyMapper(name, opts);
+  return {
+    get: (key) =>
+      span('db.get', name, async () => {
+        const out = await ddb().send(new GetCommand({ TableName: table(), Key: m.primaryKey(key) }));
+        return stripInternal<T>(out.Item);
+      }),
+
+    put: (item, putOpts) =>
+      span('db.put', name, async () => {
+        await ddb().send(
+          new PutCommand({
+            TableName: table(),
+            Item: m.toItem(item),
+            ...(putOpts?.ifNotExists ? { ConditionExpression: 'attribute_not_exists(pk)' } : {}),
+          }),
+        );
+        return item;
+      }),
+
+    update: (key, patch) =>
+      span('db.update', name, async () => {
+        for (const k of Object.keys(patch)) {
+          if (m.keyFields.has(k) && patch[k] !== key[k])
+            throw new Error(`collection "${name}": cannot change key attribute "${k}"`);
+        }
+        const tableName = table();
+        const Key = m.primaryKey(key);
+        const { expr, names, values } = setExpression(patch as Record<string, unknown>, m.keyFields);
+        const out = await ddb().send(
+          new UpdateCommand({
+            TableName: tableName,
+            Key,
+            UpdateExpression: expr,
+            ExpressionAttributeNames: { ...names, '#pk': 'pk' },
+            ...(Object.keys(values).length ? { ExpressionAttributeValues: values } : {}),
+            ConditionExpression: 'attribute_exists(#pk)',
+            ReturnValues: 'ALL_NEW',
+          }),
+        );
+        let item = out.Attributes ?? {};
+        if (Object.keys(patch).some((k) => m.derivedSources.has(k))) {
+          const d = setExpression(m.derived(item), new Set());
+          const again = await ddb().send(
+            new UpdateCommand({
+              TableName: tableName,
+              Key,
+              UpdateExpression: d.expr,
+              ExpressionAttributeNames: { ...d.names, '#pk': 'pk' },
+              ...(Object.keys(d.values).length ? { ExpressionAttributeValues: d.values } : {}),
+              ConditionExpression: 'attribute_exists(#pk)',
+              ReturnValues: 'ALL_NEW',
+            }),
+          );
+          item = again.Attributes ?? item;
+        }
+        return stripInternal<T>(item)!;
+      }),
+
+    delete: (key) =>
+      span('db.delete', name, async () => {
+        await ddb().send(new DeleteCommand({ TableName: table(), Key: m.primaryKey(key) }));
+      }),
+
+    query: (values, q = {}) =>
+      span('db.query', name, async () => {
+        const out = await ddb().send(new QueryCommand(m.queryInput(values, q, table())));
+        const page: Page<T> = { items: (out.Items ?? []).map((i) => stripInternal<T>(i)!) };
+        const cursor = encodeCursor(out.LastEvaluatedKey);
+        if (cursor) page.cursor = cursor;
+        return page;
+      }),
+  };
+}
+
+/** `SET #a = :a, ... REMOVE #b` from a patch; `undefined`/`null` values are removed. */
+export function setExpression(
+  patch: Record<string, unknown>,
+  skip: Set<string>,
+): { expr: string; names: Record<string, string>; values: Record<string, unknown> } {
+  const sets: string[] = [];
+  const removes: string[] = [];
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  let i = 0;
+  for (const [k, v] of Object.entries(patch)) {
+    if (skip.has(k)) continue;
+    const n = `#f${i}`;
+    names[n] = k;
+    if (v === undefined || v === null) removes.push(n);
+    else {
+      values[`:v${i}`] = v;
+      sets.push(`${n} = :v${i}`);
+    }
+    i++;
+  }
+  const parts: string[] = [];
+  if (sets.length) parts.push(`SET ${sets.join(', ')}`);
+  if (removes.length) parts.push(`REMOVE ${removes.join(', ')}`);
+  if (!parts.length) {
+    // No-op update still verifies existence.
+    names['#c'] = '_c';
+    parts.push('SET #c = #c');
+  }
+  return { expr: parts.join(' '), names, values };
+}
+
+export const db: Db = {
+  collection,
+  raw: () => ({ client: ddb(), table: table() }),
+};

package/src/events.ts

@@ -0,0 +1,42 @@
+import { getBindings } from './bindings.ts';
+import { client } from './clients.ts';
+import { currentTrace } from './context.ts';
+import { span } from './telemetry.ts';
+
+export interface Events {
+  publish<T = unknown>(type: string, detail: T): Promise<void>;
+}
+
+/** Envelope inside EventBridge `detail`, so the trace survives the hop. */
+export interface EventEnvelope<T = unknown> {
+  data: T;
+  trace: string;
+}
+
+export const events: Events = {
+  publish: (type, detail) =>
+    span('events.publish', type, async () => {
+      const b = getBindings();
+      if (!b.bus) throw new Error('This app has no event bus. Add an "events" entry to platform.json.');
+      const envelope: EventEnvelope = { data: detail, trace: currentTrace() };
+      const { PutEventsCommand } = await import('@aws-sdk/client-eventbridge');
+      const out = await (await client('events')).send(
+        new PutEventsCommand({
+          Entries: [
+            {
+              EventBusName: b.bus.name,
+              Source: `platform.${b.app}`,
+              DetailType: type,
+              Detail: JSON.stringify(envelope),
+            },
+          ],
+        }),
+      );
+      if (out.FailedEntryCount) {
+        const e = out.Entries?.find((x) => x.ErrorCode);
+        throw new Error(
+          `events.publish("${type}") failed: ${e?.ErrorCode ?? 'unknown'} ${e?.ErrorMessage ?? ''}`.trim(),
+        );
+      }
+    }),
+};

package/src/http.ts

@@ -0,0 +1,82 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { Readable } from 'node:stream';
+
+/**
+ * Minimal Node `http` ⇄ web `fetch` adapter (no framework dependency).
+ * Streams request and response bodies, preserves multiple Set-Cookie headers.
+ */
+export type FetchFn = (request: Request) => Promise<Response>;
+
+export function toRequest(req: IncomingMessage, signal?: AbortSignal): Request {
+  const host = req.headers.host ?? 'localhost';
+  const url = new URL(req.url ?? '/', `http://${host}`);
+  const headers = new Headers();
+  for (let i = 0; i < req.rawHeaders.length; i += 2) {
+    const k = req.rawHeaders[i]!;
+    const v = req.rawHeaders[i + 1]!;
+    if (k.startsWith(':')) continue;
+    headers.append(k, v);
+  }
+  const method = req.method ?? 'GET';
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+  return new Request(url, {
+    method,
+    headers,
+    ...(hasBody ? { body: Readable.toWeb(req) as ReadableStream, duplex: 'half' } : {}),
+    ...(signal ? { signal } : {}),
+  } as RequestInit);
+}
+
+export async function writeResponse(res: ServerResponse, response: Response): Promise<void> {
+  const headers: Record<string, string | string[]> = {};
+  response.headers.forEach((value, key) => {
+    if (key === 'set-cookie') return;
+    headers[key] = value;
+  });
+  const cookies = response.headers.getSetCookie();
+  if (cookies.length) headers['set-cookie'] = cookies;
+  res.writeHead(response.status, response.statusText || undefined, headers);
+  if (!response.body) {
+    res.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!res.write(value)) await new Promise<void>((r) => res.once('drain', r));
+    }
+  } finally {
+    res.end();
+  }
+}
+
+export function createNodeServer(fetchFn: FetchFn): Server {
+  return createServer((req, res) => {
+    const controller = new AbortController();
+    res.once('close', () => {
+      if (!res.writableFinished) controller.abort();
+    });
+    fetchFn(toRequest(req, controller.signal))
+      .then((response) => writeResponse(res, response))
+      .catch((e) => {
+        if (!res.headersSent) {
+          res.writeHead(500, { 'content-type': 'application/json' });
+          res.end(
+            JSON.stringify({ error: { code: 'internal', message: String((e as Error)?.message ?? e) } }),
+          );
+        } else res.destroy(e as Error);
+      });
+  });
+}
+
+/** Parse `host:port` (IPv6 in brackets allowed). */
+export function parseEndpoint(endpoint: string): { host: string; port: number } {
+  const i = endpoint.lastIndexOf(':');
+  if (i <= 0) throw new Error(`Invalid listen endpoint "${endpoint}" (expected host:port)`);
+  const host = endpoint.slice(0, i).replace(/^\[|\]$/g, '');
+  const port = Number(endpoint.slice(i + 1));
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid port in "${endpoint}"`);
+  return { host, port };
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @ericminassian/platform — the only thing app code imports. Cloud-neutral
+ * interfaces backed by AWS (DynamoDB, SQS, EventBridge, S3, SSM, Cognito)
+ * through bindings the engine injects. Under `plat dev` the same code talks to
+ * the AWS Emulator, so there is exactly one implementation.
+ *
+ * CONTRACT: these exports are documented in templates/app/AGENTS.md and used
+ * by every app. Keep signatures stable.
+ */
+export type { PlatformUser } from '@ericminassian/platform-core';
+export { type AppInfo, app } from './app.ts';
+export { type Auth, auth } from './auth/index.ts';
+export { setRoute } from './context.ts';
+export {
+  type Collection,
+  type CollectionOptions,
+  type Db,
+  db,
+  type KeyValue,
+  type Page,
+  type QueryOptions,
+} from './db.ts';
+export { type Events, events } from './events.ts';
+export { type Queue, queue } from './queue.ts';
+export { type Secrets, secrets } from './secrets.ts';
+export { type Store, type StoredObject, storage } from './storage.ts';
+export { log, metrics } from './telemetry.ts';
+export { invokeJob } from './worker.ts';
+
+export interface Metrics {
+  count(name: string, n?: number): void;
+  value(name: string, value: number, unit?: string): void;
+}
+
+export interface Logger {
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  info(msg: string, fields?: Record<string, unknown>): void;
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  error(msg: string, fields?: Record<string, unknown> | unknown): void;
+}

package/src/queue.ts

@@ -0,0 +1,67 @@
+import { getBindings } from './bindings.ts';
+import { client } from './clients.ts';
+import { currentTrace } from './context.ts';
+import { span } from './telemetry.ts';
+
+export interface Queue<T> {
+  send(body: T, opts?: { delaySeconds?: number }): Promise<void>;
+  sendBatch(bodies: T[]): Promise<void>;
+}
+
+function queueUrl(name: string): string {
+  const queues = getBindings().queues;
+  const q = queues[name];
+  if (!q) {
+    const declared = Object.keys(queues);
+    throw new Error(
+      `Unknown queue "${name}". Declared queues: ${declared.length ? declared.join(', ') : '(none)'} — add it under "queues" in platform.json.`,
+    );
+  }
+  return q.url;
+}
+
+function traceAttribute(trace: string) {
+  return { trace: { DataType: 'String', StringValue: trace } };
+}
+
+export function queue<T = unknown>(name: string): Queue<T> {
+  return {
+    send: (body, opts) =>
+      span('queue.send', name, async () => {
+        const { SendMessageCommand } = await import('@aws-sdk/client-sqs');
+        await (await client('sqs')).send(
+          new SendMessageCommand({
+            QueueUrl: queueUrl(name),
+            MessageBody: JSON.stringify(body),
+            MessageAttributes: traceAttribute(currentTrace()),
+            ...(opts?.delaySeconds !== undefined ? { DelaySeconds: opts.delaySeconds } : {}),
+          }),
+        );
+      }),
+    sendBatch: (bodies) =>
+      span('queue.send', name, async () => {
+        const url = queueUrl(name);
+        const trace = currentTrace();
+        const { SendMessageBatchCommand } = await import('@aws-sdk/client-sqs');
+        const sqs = await client('sqs');
+        for (let i = 0; i < bodies.length; i += 10) {
+          const chunk = bodies.slice(i, i + 10);
+          const out = await sqs.send(
+            new SendMessageBatchCommand({
+              QueueUrl: url,
+              Entries: chunk.map((b, j) => ({
+                Id: String(i + j),
+                MessageBody: JSON.stringify(b),
+                MessageAttributes: traceAttribute(trace),
+              })),
+            }),
+          );
+          if (out.Failed?.length) {
+            throw new Error(
+              `queue "${name}": ${out.Failed.length} message(s) failed: ${out.Failed[0]?.Message ?? out.Failed[0]?.Code}`,
+            );
+          }
+        }
+      }),
+  };
+}

package/src/secrets.ts

@@ -0,0 +1,57 @@
+import { getBindings } from './bindings.ts';
+import { client } from './clients.ts';
+import { span } from './telemetry.ts';
+
+export interface Secrets {
+  /** Throws if missing. Stage value wins over the app-wide shared value. Cached ~5 min. */
+  get(name: string): Promise<string>;
+  getOptional(name: string): Promise<string | undefined>;
+}
+
+const TTL_MS = 5 * 60 * 1000;
+const cache = new Map<string, { value: string | undefined; at: number }>();
+
+async function read(path: string): Promise<string | undefined> {
+  try {
+    const { GetParameterCommand } = await import('@aws-sdk/client-ssm');
+    const out = await (await client('ssm')).send(
+      new GetParameterCommand({ Name: path, WithDecryption: true }),
+    );
+    return out.Parameter?.Value;
+  } catch (e) {
+    if ((e as { name?: string })?.name === 'ParameterNotFound') return undefined;
+    throw e;
+  }
+}
+
+async function lookup(name: string): Promise<string | undefined> {
+  const hit = cache.get(name);
+  if (hit && Date.now() - hit.at < TTL_MS) return hit.value;
+  const { secrets } = getBindings();
+  const value = await span(
+    'secrets.get',
+    name,
+    async () => (await read(`${secrets.path}${name}`)) ?? read(`${secrets.sharedPath}${name}`),
+  );
+  cache.set(name, { value, at: Date.now() });
+  return value;
+}
+
+export const secrets: Secrets = {
+  async get(name) {
+    const v = await lookup(name);
+    if (v === undefined) {
+      const b = getBindings();
+      throw new Error(
+        `Secret ${name} is not set. Run: plat secrets set ${b.app} ${name} --stage ${b.stage}  (or without --stage for all stages)`,
+      );
+    }
+    return v;
+  },
+  getOptional: (name) => lookup(name),
+};
+
+/** Drop cached values (tests). */
+export function clearSecretsCache(): void {
+  cache.clear();
+}