@tempmd/platform

Server SDK for products that create and govern temp.md previews for their own customers. Resources are isolated by Application and can be associated with your own opaque customer and project identifiers.

Install

npm install @tempmd/platform

Requires Node.js 20+ or another server runtime with Fetch, Web Crypto, Blob, and typed arrays.

Create an Application key

Create an Organization and Application in the Platform dashboard, then create an Application key. The raw key is revealed once and starts with tempmd_app_. Keep it on your server.

import { TempmdPlatform } from "@tempmd/platform";

const tempmd = new TempmdPlatform({
  apiKey: process.env.TEMPMD_APPLICATION_KEY!,
  clientIdentity: "my-builder/1.0.0",
});

Publish a customer preview

const preview = await tempmd.createPreview({
  externalSubjectId: user.id,
  externalProjectId: project.id,
  files: [
    {
      path: "index.html",
      data: html,
      contentType: "text/html; charset=utf-8",
    },
  ],
  spaMode: true,
});

console.log(preview.canonicalUrl);

Use opaque identifiers from your own system. Do not send names, email addresses, or other personal data as external IDs.

Update the same preview

Create a new version without changing the canonical URL:

const next = await tempmd.createVersion(preview.tempId, {
  externalSubjectId: user.id,
  externalProjectId: project.id,
  files: nextFiles,
  spaMode: true,
});

List, inspect, and revoke

Application keys can only access previews belonging to their Application.

const previews = await tempmd.listPreviews({
  externalProjectId: project.id,
});

const detail = await tempmd.getPreview(preview.tempId);

await tempmd.revokePreview(preview.tempId);

Delegate a browser upload

Application keys are server-only. Mint a short-lived grant and return only its token to the browser or Electron renderer:

const grant = await tempmd.createPublishGrant({
  operation: "create",
  externalSubjectId: user.id,
  externalProjectId: project.id,
  ttlSeconds: 300,
  maxFiles: 100,
  maxFileBytes: 10_000_000,
  maxTotalBytes: 50_000_000,
});

return { publishGrant: grant.token };

In the client, use the grant with @tempmd/client:

import { TempmdClient, TempmdPreviewClient } from "@tempmd/client";

const previews = new TempmdPreviewClient(
  new TempmdClient({ accountToken: publishGrant })
);

const result = await previews.publishPreview({ files });

The browser receives a platform-owned preview record without an update token. To update it, mint a fresh operation: "update" grant with the existing previewId, and pass that grant to a new browser client. Keep preview status and revocation on your server through this SDK.

Revoke an unused grant with revokePublishGrant(grant.id).

Review requests

A review request freezes the current version for an immutable approval link.

const review = await tempmd.createReviewRequest(preview.tempId, {
  label: "Homepage approval",
  ttlSeconds: 7 * 24 * 60 * 60,
});

console.log(review.reviewUrl);

const reviews = await tempmd.listReviewRequests(preview.tempId);

Usage

const usage = await tempmd.getUsage({
  from: "2026-08-01",
  to: "2026-09-01",
});

console.log(usage.totals.previewCreates);
console.log(usage.totals.bytesDelivered);

Verify signed webhooks

Always verify the raw request body before parsing it. The timestamp tolerance defaults to five minutes.

import { verifyWebhookSignature } from "@tempmd/platform";

const body = await request.text();
const valid = await verifyWebhookSignature({
  secret: process.env.TEMPMD_WEBHOOK_SECRET!,
  timestamp: request.headers.get("x-tempmd-timestamp") ?? "",
  signature: request.headers.get("x-tempmd-signature") ?? "",
  body,
});

if (!valid) return new Response("Invalid signature", { status: 401 });

const event = JSON.parse(body);

Webhook delivery is signed, retried, and safe to process idempotently by event identifier.

Errors and cancellation

Every operation accepts an AbortSignal where applicable. HTTP failures throw PlatformApiError with status, code, optional requestId, optional retryAfter, and a secret-redacted response body.

import { PlatformApiError } from "@tempmd/platform";

try {
  await tempmd.getPreview(previewId);
} catch (error) {
  if (error instanceof PlatformApiError) {
    console.error(error.status, error.code, error.requestId);
  }
}

Security requirements

• Never expose an Application key in browser bundles, renderer state, URLs, logs, analytics, webhooks, or rendered content.
• Give untrusted clients only short-lived publish grants with explicit limits.
• Treat webhook secrets and raw Application keys as one-time-reveal secrets.
• Use opaque external subject and project identifiers.
• Revoke keys and grants immediately when they are no longer needed.

Main exports

• TempmdPlatform — preview, version, grant, review, and usage operations.
• PlatformApiError — structured HTTP failures.
• verifyWebhookSignature — constant-time HMAC verification with replay tolerance.
• Public TypeScript types for previews, versions, grants, reviews, and usage.

See the preview infrastructure overview.