Function SDK reference

The complete contract between your TypeScript and the OmniLab runtime.

Handler exports

Your file must export exactly one handler, named after the function's kind. The build checks that export against the type for that kind, so a missing or wrongly shaped handler fails the build instead of failing in production.

The types come from the ./omnilab module, available in every function:

import { OmniLab } from "./omnilab";
import type { PlatformEventHandler, ContactCreatePreHandler } from "./omnilab";

Handlers may be async. Only TypeScript is supported, in a single file whose entry point is user.ts.

Input shapes

PlatformEvent

type PlatformEvent = {
  type: string;   // e.g. "touchpoint.completed.v1"
  id: string;     // unique per event — deduplicate on this
  time: string;   // ISO-8601
  source: string;
  data: Json;     // the event payload, exactly as OmniLab published it
};

Delivery is at-least-once. The same id can arrive more than once, so make external side effects idempotent.

Event payloads

data differs by event type. Every payload carries the same context block, and each family adds its own fields on top.

data: {
  web_context:   { utm: { … }, user_agent: { is_bot, is_mobile, is_desktop, is_tablet } },
  interaction:   { interaction_id, interaction_display_name, interaction_public_key, interaction_snapshot_id },
  contact:       { contact_id },
  group_context: { group_id, unique_key },
  tenant_context:{ subdomain, db_name },
}

contact.contact_id is the id you pass to OmniLab.Contact.get and the field writers, so it is the one you will read most.

Read data defensively even so. Cast it to the shape you expect, and treat every field as possibly absent rather than assuming a payload is fully populated.

Hook contracts

Every hook input carries a context object, but only contact.verification populates its idempotency_key. OmniLab never retries a hook invocation; the key exists because the operation around it can be attempted again, and it stays stable across those attempts — forward it to any provider that accepts one so a repeat cannot cause a duplicate send. An explicit resend deliberately carries a different key.

contact.create.pre receives an empty key. Creating a contact has no external side effect OmniLab owns, so no key is computed for it. If your handler calls out to a provider that charges or mutates something, you have to supply your own dedupe value — the contact's email is the usual choice.

Build your return value with OmniLab.Flow — never return a plain object:

OmniLab.Flow.continue(result?)          // proceed, optionally supplying values
OmniLab.Flow.deny(code, message)        // block the operation

contact.create.pre

Runs before a contact is stored, from signup, admin, import, or API.

{
  contact: {
    email: string;
    phone_number: string;
    firstname: string;
    lastname: string;
    custom_fields: Record<string, string>;
  };
  source: string;                    // always "signup" today
  context: { idempotency_key: string };   // empty for this hook point
}

Continuing accepts an optional email, an optional phone_number, and custom_fields. Only the fields you return are applied — omit a field to leave it as submitted. Denying rejects the contact and the operation fails.

The hook runs before the contact is stored and before any connected CRM is updated, so the email you return is the value OmniLab persists and the value it forwards downstream. That is what makes normalizing here worthwhile: returning a lowercased address prevents Foo@example.com and foo@example.com becoming two profiles.

source is declared as a string so more origins can be added, but every call today sends "signup". Don't branch on it yet.

contact.verification

Runs when a double opt-in verification message needs to be sent. Your handler is responsible for actually delivering it.

{
  contact: { email: string; firstname: string; lastname: string };
  interaction: { id: string; public_key: string };
  verification_url: string;
  expires_at: string;
  context: { idempotency_key: string };
}

Continuing accepts an optional provider_message_id, which is recorded in the execution log and changes nothing. Continuing means the dispatch was accepted, not that the message arrived. Denying makes the signup fail.

SDK surface

These are the only calls that reach outside the sandbox. Everything else in your handler is pure computation.

Config

Http

Every request is checked against the function's allowed-hosts list, and internal or private addresses are refused whether or not you listed them. Only http and https are allowed. Each request has a 1500 ms timeout, and a response body larger than 4 MiB is truncated with a header marking it.

Contact

All three resolve to the same object, so a write hands back the contact it just changed and you rarely need a follow-up read:

{
  id: string;                              // "contacts/<uuid>"
  firstname: string;
  lastname: string;
  email: string;
  phoneNumber: string;
  externalId: string;
  barcode: string;
  customFields: Record<string, string>;    // the only writable part
  emailVerified: boolean;
  optin: boolean;
  hasAcceptedTerms: boolean;
  isBlacklisted: boolean;
  blacklistReason: string;
  originInteraction: string;
}

Every field except customFields is read-only from a function. Custom field values are always strings.

Custom field keys beginning system. or feature. are reserved and rejected with INVALID_ARGUMENT. A key can be up to 128 characters and a value up to 4 KB. Prefer setCustomFields for several keys: it is one call against your budget rather than several.

Logging

console.log, console.info, console.warn, console.error, console.debug, and console.trace are captured into the execution record and shown in the Test tab. Capture is limited to 16 KB total, 256 lines, and 2 KB per line; beyond that the log is marked truncated.

Designing within the SDK

The calls above are the whole surface. When your logic needs more, reach your own systems over HTTP and do the work there. Three consequences to plan around:

Keep your state outside the function. Every invocation starts fresh, so a value you assign at module level is gone by the next one. Persist what you need to contact custom fields, or to your own service.

Reach other OmniLab records through the API. Functions read and write contacts. For transactions, rewards, smart links, and everything else, call the OmniLab API from your own systems instead.

Functions run on triggers, not on a clock. There is no way to schedule one. If you need work to happen at a set time, run it from your own scheduler.

Error codes

SDK failures throw a typed error carrying a code, a message, and a retryable flag.

Error messages are meant for a human reading the execution log, and their wording is not stable. Never parse one — branch on the code.

Failure semantics

Subscribable event types

These are the event types the picker offers, grouped as it groups them and searchable within it. If OmniLab emits a type that is not listed, you can add it with the custom event field.

Two platform rules apply on top of this list. Anonymous page-visit events are never subscribable, and OmniLab refuses a subscription that names one. And an event that carries no identified contact never triggers a function, whatever your subscription says.

Filters accept a closed set of keys — tenant, group, interaction, and contact — combined with AND and matched exactly.

Limits

Per invocation

The timeout covers your handler only. The time OmniLab spends preparing to run it is not charged against your limit — the execution detail reports the two separately.

Per function

Per tenant

Retention and truncation

Build

There are no rate limits on invocation. Volume is bounded instead by the SDK call budget, the subscription cap, and the exclusion of anonymous page-visit events.

Related