effing-cloud-sdk

Official JavaScript/TypeScript SDK for Effing Cloud.

Mint signed URLs for image, annie, and effie modules deployed to Effing Cloud — no manual segment construction, no need to depend on @effing/serde directly.

Install

npm install effing-cloud-sdk
# or
pnpm add effing-cloud-sdk

Zero runtime dependencies — the signing primitive is bundled into the SDK.

Usage

The recommended API is the EffingCloudClient class. Configure it once with your tenant slug, project slug, and URL secret, then call mintSignedUrl() for each render.

import { EffingCloudClient } from "effing-cloud-sdk";

const client = new EffingCloudClient({
  tenant: "acme",
  project: "posters",
  secret: process.env.EFFING_URL_SECRET!,
});

const url = await client.mintSignedUrl({
  kind: "effie",
  id: "poster",
  props: { imageUrl: "https://cdn.example.com/sky.jpg", duration: 5 },
  bounds: { width: 1080, height: 1920 },
});

// https://fn.effing.dev/acme/posters/effie/<segment>

kind is one of "image" | "annie" | "effie" — the module type you want to invoke.

Prop naming

props is JSON-serialized verbatim — keys round-trip exactly as you write them. The server does run a recursive snake_case → camelCase conversion during deserialization, so any image_url-style keys (typical when minting from a Python or Go caller) surface as imageUrl inside the module. Pure camelCase keys pass through unchanged.

One-shot function

A standalone mintSignedUrl() is also exported, useful for scripts and tests:

import { mintSignedUrl } from "effing-cloud-sdk";

const url = await mintSignedUrl({
  tenant: "acme",
  project: "posters",
  kind: "effie",
  id: "poster",
  props: { ... },
  bounds: { width: 1080, height: 1920 },
  secret: process.env.EFFING_URL_SECRET!,
});

Tagging runs

Tags travel inside the signed segment and surface in your run / render reports. Pass them as an object (recommended) or as a list of bare values and/or name:value strings:

const url = await client.mintSignedUrl({
  kind: "effie",
  id: "poster",
  props: { ... },
  bounds: { width: 1080, height: 1920 },
  tags: { campaign: "summer", env: "prod" },
});

// Array form — useful for bare tags or pre-formatted entries.
const url2 = await client.mintSignedUrl({
  kind: "effie",
  id: "poster",
  props: { ... },
  bounds: { width: 1080, height: 1920 },
  tags: ["vip", "env:prod"],
});

Tag names in the object form must not contain : — that character is reserved as the name/value separator in the array form.

Custom base URL

new EffingCloudClient({
  tenant: "acme",
  project: "posters",
  secret: process.env.EFFING_URL_SECRET!,
  baseUrl: "https://fn.example.com",
});

API

new EffingCloudClient(opts)

| Option | Type | Default | Description | | --------- | --------- | ----------------------- | ---------------------------------------------- | | tenant | string | — | Your tenant slug. | | project | string | — | Your project slug. | | secret | string | — | URL secret from effing-cloud url-secret. | | baseUrl | string? | https://fn.effing.dev | Override for self-hosted or staging endpoints. |

client.mintSignedUrl({ kind, id, props, bounds, tags? })

Returns Promise<string> — the fully-qualified signed URL.

mintSignedUrl(opts)

Standalone equivalent that takes tenant, project, secret, and optional baseUrl inline alongside the module fields. Returns Promise<string>.

Types

type FnKind = "image" | "annie" | "effie";
interface FnBounds {
  width: number;
  height: number;
}
type FnTags = Record<string, string> | string[];