@ema-unlimited/frontier-apps-sdk

SDK for Frontier Apps — provides database, storage, and Ema API access via the frontier-apps-gateway. Each capability is a separate subpath import so apps only pull in what they use.

Status: v0.x — DB routes (/v1/db/*) deployed. Storage routes (/v1/storage/*) added in 0.2.0 (currently in rc channel; see the rc dist-tag). Ema API routes are planned for a future release.

Why

Every deployed Frontier App previously talked to MongoDB directly. A single runaway query could saturate the replica set for every app. This SDK forces all traffic through the gateway where a safety blocklist, per-app connection pool, and audit trail live.

App code only changes its import line — the call surface (Mongoose Schema, model(), query chaining) is preserved.

Install

pnpm add @ema-unlimited/frontier-apps-sdk mongoose

mongoose is a required peer dependency for the DB subpath. The SDK re-exports mongoose.Schema and InferSchemaType so the migration from a direct Mongoose connection is a one-line import swap. The SDK never opens a MongoDB connection itself — Schema construction is pure JS path-building.

The package is published to the public npm registry — no auth required:

npm install @ema-unlimited/frontier-apps-sdk

Subpaths

@ema-unlimited/frontier-apps-sdk/ema (Ema API proxy) is planned but not yet added.

Root (@ema-unlimited/frontier-apps-sdk)

The root export is gateway infrastructure only — not a capability.

import { initGatewayClient, FrontierError } from '@ema-unlimited/frontier-apps-sdk'
import type { GatewayClientConfig } from '@ema-unlimited/frontier-apps-sdk'

One-time client init

initGatewayClient({
  gatewayUrl: process.env.FRONTIER_GATEWAY_URL!,  // injected by publisher
  appId: process.env.APP_ID!,                      // injected by publisher
})

APP_ID is the publisher-provided value: a full UUID for published scope, preview-{shortId} for preview scope. Call this once at app boot — it wires the shared transport used by all subpaths.

MongoDB (@ema-unlimited/frontier-apps-sdk/mongodb)

Define a schema (mechanical swap from Mongoose)

// Before
import mongoose, { Schema, type InferSchemaType } from 'mongoose'

// After — only the import line changes
import { Schema, model, type InferSchemaType } from '@ema-unlimited/frontier-apps-sdk/mongodb'

const noteSchema = new Schema(
  {
    userId: { type: String, required: true, index: true },
    title: { type: String, required: true },
    content: { type: String, default: '' },
  },
  { timestamps: true },
)

export type NoteDocument = InferSchemaType<typeof noteSchema>
export const Note = model<NoteDocument>('Note', noteSchema)

Query

const notes = await Note.find({ userId }).sort({ createdAt: -1 }).limit(20)

const note = await Note.findOneAndUpdate(
  { _id: id, userId },
  { $set: { title: 'New' } },
  { new: true },
)

await Note.deleteOne({ _id: id, userId })

Supported operations

The query chain is lazy — .sort(), .limit(), .skip(), .lean() return the same QueryBuilder and the HTTP request fires only when awaited. .lean() is a no-op (the gateway always returns plain JSON).

bulkWrite

bulkWrite takes the same op array mongoose.Model.bulkWrite takes:

await LineItem.bulkWrite([
  { updateOne: { filter: { _id: id }, update: { $set: { verdict: 'pass' } } } },
  { insertOne: { document: { sku: 'new' } } },
  { deleteOne: { filter: { sku: 'old' } } },
])

Ordering differs from Mongoose. This defaults to ordered: false where Mongoose defaults to true, so a failing op does not discard the rest of the batch. Pass { ordered: true } for stop-at-first-error semantics.

A batch is capped at 1000 ops, and the whole request body at 10 MiB — chunk above either. A failed batch throws even when some ops landed; the error message carries the counters that did apply.

Indexes

// Idempotent: safe to call at every boot.
await Note.createIndex({ userId: 1, createdAt: -1 })
await Person.createIndex({ email: 1 }, { unique: true })
const live = await Note.listIndexes()

Key order is significant for a compound index and is preserved on the wire, so build the key spec as an object literal. Supported options: name, unique, sparse, hidden, expireAfterSeconds, partialFilterExpression. Any other option is rejected, rather than dropped, so an app never believes it holds a constraint the database is not enforcing.

Re-creating an index with an identical spec is a no-op. The same name with a different spec is an IndexOptionsConflict from the server. A collection is capped at 64 indexes, MongoDB's own limit.

createIndex uses a 5-minute timeout rather than the usual 30 seconds: an index build runs to completion before the command returns.

Blocked at the facade level

These throw synchronously before any network call:

• .populate() → use aggregate with $lookup
• .drop() / dropCollection() → schema management is not exposed
• dropIndex() → use createIndex and listIndexes

The gateway additionally blocks $where, $function, $accumulator, $out, mapReduce, and unbounded find({}) calls. These return HTTP 400, which the SDK surfaces as a FrontierDbError.

Error handling

import { FrontierError } from '@ema-unlimited/frontier-apps-sdk'
import { FrontierDbError } from '@ema-unlimited/frontier-apps-sdk/mongodb'

try {
  await Note.find({})
} catch (err) {
  if (err instanceof FrontierDbError) {
    console.error(err.status, err.code, err.message)
  }
  // Or catch any SDK error across subpaths:
  if (err instanceof FrontierError) { ... }
}

Storage (@ema-unlimited/frontier-apps-sdk/storage)

Per-app file storage backed by GCS. The SDK never touches GCS credentials — the gateway mints short-lived V4 signed URLs (5-min PUT, 15-min GET) and the browser/Node client does the actual byte transfer direct to storage.googleapis.com. The control plane (auth, content-type validation, quota, audit) runs at the gateway; the data plane skips it.

Storage is a pure byte store — it never parses your files — so it accepts any well-formed content type. There is no upload allow-list to grow. Safety against active content is enforced at serve time: the gateway serves text/html, image/svg+xml, and */xml objects with Content-Disposition: attachment so they download instead of executing inline on the shared GCS origin. (This does not affect <img> / <video> / <audio> embeds — browsers ignore Content-Disposition for subresource loads.)

Key layout

Every key the SDK sends is sanitised and prefixed server-side:

tenants/<tenantId>/frontier-apps/<appId>/uploads/<your-key>

Tenant + app are resolved from the gateway (per-app K8s secret) — the SDK cannot influence them. User-supplied keys must match [A-Za-z0-9._/-] and cannot start with / or contain .. / NUL.

High-level upload (handles signing for you)

import { put } from '@ema-unlimited/frontier-apps-sdk/storage'

const blob = new Blob([fileBytes], { type: 'image/png' })
const meta = await put(`users/${userId}/avatar.png`, blob, {
  contentType: 'image/png',
})
// → { key, size, contentType }

Under the hood put() does sign → PUT (direct to GCS) → confirm. If the PUT fails, confirm-put is not called — no orphan records.

Browser-direct upload (large files, no Node proxy hop)

When the upload comes from a browser, mint the URL server-side and let the browser do the PUT. The same Content-Type + size are pinned into the signature, so the caller can't enlarge or retype the upload after the gateway authorizes.

import { signPut, confirmPut } from '@ema-unlimited/frontier-apps-sdk/storage'

// 1. Server side — mint the signed URL.
const signed = await signPut(`users/${userId}/big.zip`, {
  contentType: 'application/zip',
  size: file.size,
})

// 2. Browser side — PUT bytes direct to GCS.
await fetch(signed.url, {
  method: 'PUT',
  headers: signed.requiredHeaders,  // includes Content-Type + X-Goog-Content-Length-Range
  body: file,
})

// 3. Server side — record the upload.
const meta = await confirmPut(`users/${userId}/big.zip`)

Read back / list / delete

import { get, getMeta, list, del } from '@ema-unlimited/frontier-apps-sdk/storage'

// Signed GET URL — usable directly in <img src>, <video src>, <a download>.
const { url, expiresAt, size, contentType } = await get(`users/${userId}/avatar.png`)

// Metadata only (no signing, no transfer).
const meta = await getMeta(`users/${userId}/avatar.png`)

// Paginated list scoped to the app's prefix.
const { items, nextCursor } = await list(`users/${userId}/`, { limit: 50 })

// Idempotent delete.
await del(`users/${userId}/avatar.png`)

Constraints (server-enforced)

Error handling

import { FrontierStorageError } from '@ema-unlimited/frontier-apps-sdk/storage'

try {
  await put('uploads/x.pdf', blob, { contentType: 'application/pdf' })
} catch (err) {
  if (err instanceof FrontierStorageError) {
    console.error(err.status, err.code, err.message)
    // err.status: HTTP status (e.g. 422 for a denied/invalid content-type or oversize)
    // err.code:   the gateway error code (e.g. "VALIDATION_ERROR") or a client
    //             classifier ("network_error" | "gcs_put_failed" | "timeout" | "aborted")
  }
}

Where things land in GCS

gs://<project-id>-frontier-apps-uploads/
  tenants/
    <tenantId>/
      frontier-apps/
        <appId>/
          uploads/
            users/<userId>/avatar.png           ← written by the storage SDK
            users/<userId>/reports/2026-Q1.pdf

The bucket is dedicated to per-app user uploads — separate from the shared <env>-emu-blobs bucket where frontier-apps-builder keeps its git snapshots. Per-tenant offboarding is a single gsutil -m rm -r gs://<bucket>/tenants/<tenantId>/ against this bucket.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

Design

See docs/design-frontier-apps-db-proxy.md.