TypeScript SDK

import { SalesOS } from '@salesos/sdk';

const salesos = new SalesOS({ apiKey: process.env.SALESOS_API_KEY });

const lead = await salesos.leads.create({ firstName: 'Ada', lastName: 'Lovelace', company: 'Analytical' });
await salesos.leads.update(lead.id, { status: 'CONTACTED' });

for await (const deal of salesos.opportunities.iterate({ owner: 'me', open: true })) {
  console.log(deal.name, deal.amount);
}

const pipelines = await salesos.request('GET', '/v1/pipelines');
const { data, status, headers, requestId } = await salesos.requestWithResponse('POST', '/v1/leads/{id}/convert', {
  pathParams: { id: lead.id },
  body: { createOpportunity: true },
});

import { callOperation } from '@salesos/sdk/operations';

const stats = await callOperation(salesos, 'leads_getStats', {});

for await (const contact of salesos.contacts.iterate({ search: 'acme' }, { maxItems: 500 })) {
  // …
}

for await (const page of salesos.accounts.pages({ limit: 200 })) {
  console.log(`page ${page.page}/${page.totalPages}`);
}

import { SalesOSError } from '@salesos/sdk';

try {
  await salesos.opportunities.update(id, { stage: 'CLOSED_WON' });
} catch (err) {
  if (err instanceof SalesOSError && err.code === 'STAGE_REQUIREMENTS_NOT_MET') {
    console.log((err.body as { missingFields: string[] }).missingFields);
  } else throw err;
}

await salesos.orders.create(order, { idempotencyKey: `order-${externalId}` }); // your own key
await salesos.leads.create(lead, { idempotencyKey: false });                    // none
await salesos.leads.list({}, { timeoutMs: 5000, signal: controller.signal });

import { SalesOS, OAuthClient, ClientCredentialsAuth, OAuthTokenAuth, SessionAuth } from '@salesos/sdk';

new SalesOS({ apiKey: 'sk_…' });
new SalesOS({ accessToken: async () => getTokenFromMyStore() });

const oauth = new OAuthClient({ clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET! });
const salesos = new SalesOS({ auth: new ClientCredentialsAuth(oauth, { scope: 'READ_LEADS WRITE_TASKS' }) });

const oauth = new OAuthClient({ clientId: 'sos_ci_…' }); // public client: no secret

// 1. Send the user to SalesOS. Keep state and codeVerifier (e.g. in the session).
const req = await oauth.createAuthorizationRequest({
  redirectUri: 'https://app.example.com/oauth/callback',
  scope: ['openid', 'email', 'offline_access', 'READ_LEADS'],
});
redirect(req.url);

// 2. On the callback: validates state, iss and error, then exchanges the code.
const code = oauth.parseCallback(callbackUrl, req.state);
const tokens = await oauth.exchangeCode({ code, redirectUri: req.redirectUri, codeVerifier: req.codeVerifier });

// 3. Use and refresh. Refresh tokens rotate: persist every new pair.
const salesos = new SalesOS({
  auth: new OAuthTokenAuth(
    oauth,
    { accessToken: tokens.access_token, refreshToken: tokens.refresh_token, expiresAt: tokens.expiresAt },
    { onTokens: (t) => saveTokens(userId, t) },
  ),
});

const auth = new SessionAuth({ accessToken, csrfToken });
const salesos = new SalesOS({ auth });
await salesos.developerOrgs.open(devOrgId); // later calls run in the developer org

import express from 'express';
import { constructWebhookEvent, verifyWebhookSignature } from '@salesos/sdk';

app.post('/salesos/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = await constructWebhookEvent(req.body, req.headers, process.env.SALESOS_WEBHOOK_SECRET!);
  } catch {
    return res.sendStatus(400);
  }
  switch (event.type) {
    case 'opportunity.won':
      console.log(event.data.record.amount); // typed from the event catalog
      break;
  }
  res.sendStatus(204);
});

// Or just the boolean (Fetch API handlers):
const ok = await verifyWebhookSignature(await request.text(), request.headers, secret, { toleranceSec: 300 });

import { readFile } from 'node:fs/promises';

const job = await salesos.bulk.createJob({
  object: 'contact',
  operation: 'upsert',
  externalIdField: 'email',
  file: await readFile('contacts.csv'),
  fileName: 'contacts.csv',
});
const done = await salesos.bulk.waitForJob(job.id, {
  onProgress: (j) => console.log(`${j.processedRows}/${j.totalRows}`),
});
if (done.failedRows) console.log(await salesos.bulk.failures(done.id));

const pkg = await salesos.metadata.retrieve();                 // { files: { path: text }, … }
const queued = await salesos.metadata.deploy({ files: pkg.files, checkOnly: true });
const done = await salesos.metadata.waitForDeploy(queued.id);  // results per component

// Tests: a check-only deploy that runs the package's tests (runTests 'SPECIFIED' | 'ALL')
const run = await salesos.metadata.runTests({ files: pkg.files, runTests: 'ALL' });
const tested = await salesos.metadata.waitForDeploy(run.id);    // tested.testResults.results[]
await salesos.metadata.getTestPolicy();                         // { requireTestsFor: ['FUNCTION', 'FLOW'] }

await salesos.functions.invoke('score_lead', { leadId });
for await (const frame of salesos.eventStream.listen({ events: ['lead.created'] })) {
  if (frame.event === 'event') console.log(JSON.parse(frame.data));
}
const usage = await salesos.apiUsage.summary({ days: 30 });