Node.js

operate-as is the official Node.js and TypeScript library. It needs Node 20 or newer and works in Bun and Deno. It's an ES module with types and no dependencies: it uses the built-in fetch and node:crypto. CommonJS code can require it on Node 20.19 or newer. Each service's actions come typed in a package of their own, such as @operate-as/sheets: install the ones you use.

Get startedCopy Anchor Link

npm install operate-as @operate-as/sheets

export OPERATE_AS_API_KEY="oa_..."

import { OperateAs } from "operate-as";

const operate = new OperateAs(process.env.OPERATE_AS_API_KEY);

const reporting = new OperateAs(process.env.OPERATE_AS_REPORTING_KEY); // reads sheets for the weekly report
const bookings = new OperateAs(process.env.OPERATE_AS_BOOKINGS_KEY); // writes to one client's calendar

import { Sheets } from "@operate-as/sheets";

const miller = operate.client("6f1c2a7e-..."); // one of your clients, by id
const rows = await new Sheets(miller).readRows({ spreadsheetId: "1BxiM...", range: "A1:D20" });
console.log(rows.status, rows.data);

const clients = await operate.clients.list();
// [{ id: "6f1c2a7e-...", name: "Miller Dental", services: ["sheets", "slack"] }]

OptionsCopy Anchor Link

const operate = new OperateAs(process.env.OPERATE_AS_API_KEY, {
  baseUrl: "https://api.operate.as", // or set OPERATE_AS_BASE_URL
  timeout: 60_000, // milliseconds, the default
  fetch: myFetch, // your own fetch, for tests or proxies
});

Service packagesCopy Anchor Link

Every service with actions has a typed package: @operate-as/<service> on npm. Its class takes a client and has each action as a method:

import { AiInbx } from "@operate-as/ai-inbx";
import { Sheets } from "@operate-as/sheets";

const miller = operate.client(clientId);

await new AiInbx(miller).replyToEmail({
  emailId,
  body: { from: "kate@millerdental.com", html: "<p>Thanks for booking!</p>" },
});
const rows = await new Sheets(miller).readRows({ spreadsheetId: "1BxiM...", range: "A1:D20" });

Every input and body is typed and documented, so your editor completes them and flags a missing or misspelled one. Each class also has request() for any endpoint of the service's own API. The packages use the operate-as your app has, and install it if it doesn't.

Each integration's page in these docs names its package. A package's version moves on when its service's actions change. Without a package, client.service("sheets").run("read_rows", input) runs any action.

Actions and pass-throughCopy Anchor Link

const sheets = new Sheets(operate.client(clientId));
const rows = await sheets.readRows<{ values: string[][] }>({ spreadsheetId: "1BxiM...", range: "A1:D20" });
rows.status; // 200: the service's own status
rows.data.values; // the service's own response

The resultCopy Anchor Link

Every action and request resolve to a Result<T>:

interface Result<T = unknown> {
  status: number; // the service's own HTTP status
  data: T; // the service's own response
  encoding: "json" | "text" | "base64"; // how data came back
}

When the service answers with a file, result.encoding is "base64" and data is the file as a base64 string. Decode it with Buffer.from(result.data, "base64"). encoding is "json" for parsed JSON and "text" for plain text. See The result.

const result = await sheets.readRows({ spreadsheetId: "1BxiM...", range: "A1:D20" });
if (result.status >= 400) console.warn("Sheets said no:", result.status, result.data);

ErrorsCopy Anchor Link

Every error is an OperateAsError:

Any other status throws a plain OperateAsError. Every error has:

message is detail with the status in front, such as 409: Miller Dental's Google access ended. .... APIConnectionError keeps the network failure as cause.

Catch reconnect-requiredCopy Anchor Link

A client's access ending won't fix itself. Catch it, tell someone, and stop working for that client:

import { OperateAsError, RateLimitError, ReconnectRequiredError, ServiceError } from "operate-as";

try {
  await sheets.addRow({ spreadsheetId: "1BxiM...", range: "A1", values: ["2026-10-16", "Jane Doe"] });
} catch (error) {
  if (error instanceof ReconnectRequiredError) {
    await notifyTeam(`${clientId}: ${error.detail}`); // "...Send them their link to reconnect."
    await pauseWorkflow(clientId);
  } else if (error instanceof RateLimitError) {
    await new Promise((resolve) => setTimeout(resolve, (error.retryAfter ?? 60) * 1000));
  } else if (error instanceof ServiceError) {
    await retryLater();
  } else if (error instanceof OperateAsError) {
    console.error(error.status, error.detail);
  } else {
    throw error;
  }
}

See Retries for what's worth retrying.

Verify webhooksCopy Anchor Link

OperateAs.webhooks.verify(payload, header, secret, options?) checks the Operate-As-Signature header and returns the event. Pass the raw body, before JSON.parse:

import express from "express";
import { OperateAs, SignatureVerificationError } from "operate-as";

const app = express();

app.post("/hooks/operate-as", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = OperateAs.webhooks.verify(
      req.body, // the raw Buffer
      req.header("Operate-As-Signature"),
      process.env.OPERATE_AS_WEBHOOK_SECRET, // whsec_...
    );
  } catch (error) {
    if (error instanceof SignatureVerificationError) return res.sendStatus(400);
    throw error;
  }

  if (event.type === "connection.expired") {
    emailClient(event.data.clientName, event.data.reconnectUrl);
  }
  res.sendStatus(204);
});

See Webhooks for the events.

TypesCopy Anchor Link

Every action, actions.run<T>() and request<T>() take a type for data. It's a promise about the service's response, not a check, so test status first.