Functions

Why functions exist

Everything in the client SDK — from('table').select(), auth, storage — runs against a thin gateway with the public anon key, gatekept by row-level security. That covers most of an app. But some logic has to live somewhere the user can't see or tamper with:

• A secret can't ship in the bundle. Your Stripe secret key, a vendor API key, an SMS auth token — these go in the backend's Secrets vault and are only readable server-side, from a function.
• Trusted logic can't run client-side. Anything where the user deciding the answer is a problem — creating a Checkout Session, validating a coupon, calling a partner API — belongs on the server.
• The browser can't reach some hosts. CORS, credentials, and signing make many vendor calls impossible (or unsafe) from the page. A function makes the call for you.

You reach a function by its slug — a short name. There are two ways to get one: use a builtin (already live, just set its secret) or write a custom function (your own TypeScript). Both are invoked exactly the same way.

How to invoke (both kinds)

From the SDK, call functions.invoke with the slug and an optional body. Like every SDK call it returns a Result — { data, error } — so you never have to wrap it in try/catch:

const { data, error } = await lingcode.functions.invoke('echo', {
  hello: 'world'
});
// data -> { hello: 'world', timestamp: '2026-06-11T…' }

Or call it over REST — handy from a server, a curl smoke test, or a non-JS client. POST to the function endpoint with an { input } body, authorized by the anon key or a signed-in user's token:

POST https://lingcode.dev/api/cloud/be/<backend-id>/functions/<slug>
Authorization: Bearer <anon-key-or-user-token>
Content-Type: application/json

{ "input": { "hello": "world" } }

The seven builtins

These are live on every backend with no deploy step. For each one you only need to set its required secret (if any) in the Secrets vault, then invoke it by slug. Start with echo to confirm your wiring works.

Smoke-test with echo

The very first thing to run on a new backend. If this returns your input back, invoke is wired and your URL + key are correct.

const { data } = await lingcode.functions.invoke('echo', { ping: 1 });
console.log(data); // { ping: 1, timestamp: '2026-06-11T…' }

Create a Stripe Checkout Session

Set STRIPE_SECRET_KEY in the Secrets vault first — it never touches the browser. Then call the builtin and redirect the user to the returned URL:

const { data, error } = await lingcode.functions.invoke('stripe-checkout', {
  price_id:    'price_123',
  success_url: 'https://yourapp.com/thanks',
  cancel_url:  'https://yourapp.com/pricing',
  mode:        'subscription'
});
if (error) throw error;
window.location.href = data.url; // hosted Stripe Checkout

Custom functions

When no builtin fits, write your own. You author custom functions in the Cloud console / IDE — you give the function a slug and its TypeScript source (this is a console authoring step, not something an agent tool does for you). They run in a sandboxed Deno runtime, invoked by the same functions.invoke(slug, body?) call as the builtins.

The contract

Your source must export default a handler. Whatever you return becomes the invoke result's data. TypeScript is supported natively — Deno runs it directly, no build step:

export default async function handler(input, ctx) {
  // ctx.secrets.MY_KEY  — your vault secrets, server-side only
  // ctx.backendId       — this backend's id
  // ctx.gateway         — the backend's own data-API base URL
  return { ok: true };   // becomes the invoke result's `data`
}

The second argument ctx is your server-side context:

ctx = {
  secrets:   { /* every secret set in the vault, by name */ },
  backendId: string,
  gateway:   string   // call your own data API through this
}

A small custom function

Reads a secret from the vault and returns JSON. The secret never leaves the server:

export default async function handler(input, ctx) {
  const key = ctx.secrets.WEATHER_API_KEY;
  const city = input.city ?? 'NYC';
  const res = await fetch(
    `https://api.example.com/weather?city=${city}&key=${key}`
  );
  const json = await res.json();
  return { city, tempC: json.temp_c };
}

Invoke it from the client exactly like a builtin — by its slug:

const { data, error } = await lingcode.functions.invoke('get-weather', {
  city: 'Tokyo'
});
if (error) throw error;
console.log(data.tempC);

The sandbox

Custom functions run in Deno with deny-by-default permissions. This is a feature, not a restriction to fight:

• No filesystem, no environment, no subprocesses, no FFI. A function can't read disk, spawn processes, or load native code.
• The only network it can reach is the backend's own gateway (ctx.gateway). A function can call your data API — but it can't exfiltrate to arbitrary hosts. (Need to reach a vendor? Use the http-fetch builtin's allow-list, or have your function call back through the gateway.)
• Memory is capped at 128 MB.

Limits

Functions are short-lived. Past the wall-clock timeout the process is SIGKILLed — there's no graceful extension. Don't put anything that runs longer than ~30 seconds in a function.

Availability

Custom functions need the Deno runtime, which is installed and live in production — custom functions work today. If a deployment ever lacks the runtime, custom invokes return 503 functions_runtime_unavailable while the builtins keep working (they don't depend on the Deno sandbox). So a 503 on a custom function is a runtime-availability signal; a builtin failing is something else. And remember — unknown_function is always a wrong-slug error, never an availability one.