Developers

TypeScript SDK

@wepeople/sdk is the official client for the WePeople Ingest API and apps statistics endpoint. Zero runtime dependencies beyond fetch — works on Node 18+, Bun, Deno, Cloudflare Workers, and the browser.

Install

npmbash

npm install @wepeople/sdk

Package source and examples: github.com/WEBX-PL/sdk-typescript.

Create a client

WePeopleClientts

import { WePeopleClient } from "@wepeople/sdk";

const client = new WePeopleClient({
  apiKey: process.env.WEPEOPLE_API_KEY!,
  baseUrl: "https://wepeople.app",
});

// Validate key before production traffic
const ping = await client.ping();
console.log(ping.app.slug);

Pass baseUrl only when targeting a non-production host. Production base URL is https://wepeople.app.

Ingest events

ingestEventsts

const result = await client.ingestEvents(
  [
    {
      eventType: "ticket.resolved",
      category: "TASK_UPDATE",
      actor: { externalId: "crm-user-42" },
      duration: 240,
      metadata: { ticket_id: "SUP-431" },
    },
  ],
  { idempotencyKey: "batch-8412" },
);

if (result.rejected > 0) {
  for (const row of result.results.rejected) {
    console.warn(`index ${row.index}: ${row.code}`);
  }
}

The SDK generates an idempotency key automatically when omitted. See POST events for field constraints.

Ingest snapshots

ingestSnapshotts

await client.ingestSnapshot({
  snapshotType: "tickets_open",
  actor: { externalId: "crm-user-42" },
  metrics: {
    tickets_open: 7,
    sla_attainment: { value: 0.92, unit: "ratio", label: "SLA" },
  },
});

Statistic manifest

putStatisticsts

await client.putStatistics([
  {
    id: "crm-hub.tickets_resolved",
    label: "Tickets resolved",
    description: "Support tickets closed per day",
    pillar: "DELIVERY",
    format: "number",
    aggregation: "count",
    sourceEventTypes: ["ticket.resolved"],
    sourceEventCategories: ["TASK_UPDATE"],
    defaultEnabled: true,
    ownedBy: "none",
  },
]);

const { statistics } = await client.getStatistics();

Guide: Custom statistics. Reference: Apps statistics.

Errors & retries

Failed responses throw typed errors with code, message, and requestId. The client retries transient failures and respects Retry-After on rate_limited.

Error handlingts

import { WePeopleApiError } from "@wepeople/sdk";

try {
  await client.ingestEvents(events);
} catch (err) {
  if (err instanceof WePeopleApiError) {
    if (err.code === "forbidden_event_type") {
      // fix whitelist in Developer settings
    }
    console.error(err.requestId, err.docsUrl);
  }
  throw err;
}

Source & OpenAPI

Types are generated from the OpenAPI spec. Canonical YAML:

Served at /openapi/v1.yaml
Source repo: sdk-typescript/openapi

See OpenAPI & SDK for codegen workflows.

Create a client

WePeopleClientts

import { WePeopleClient } from "@wepeople/sdk";

const client = new WePeopleClient({
  apiKey: process.env.WEPEOPLE_API_KEY!,
  baseUrl: "https://wepeople.app",
});

// Validate key before production traffic
const ping = await client.ping();
console.log(ping.app.slug);

Pass baseUrl only when targeting a non-production host. Production base URL is https://wepeople.app.

Ingest events

ingestEventsts

const result = await client.ingestEvents(
  [
    {
      eventType: "ticket.resolved",
      category: "TASK_UPDATE",
      actor: { externalId: "crm-user-42" },
      duration: 240,
      metadata: { ticket_id: "SUP-431" },
    },
  ],
  { idempotencyKey: "batch-8412" },
);

if (result.rejected > 0) {
  for (const row of result.results.rejected) {
    console.warn(`index ${row.index}: ${row.code}`);
  }
}

The SDK generates an idempotency key automatically when omitted. See POST events for field constraints.

await client.ingestSnapshot({ snapshotType: "tickets_open", actor: { externalId: "crm-user-42" }, metrics: { tickets_open: 7, sla_attainment: { value: 0.92, unit: "ratio", label: "SLA" }, }, });

Statistic manifest

putStatisticsts

await client.putStatistics([
  {
    id: "crm-hub.tickets_resolved",
    label: "Tickets resolved",
    description: "Support tickets closed per day",
    pillar: "DELIVERY",
    format: "number",
    aggregation: "count",
    sourceEventTypes: ["ticket.resolved"],
    sourceEventCategories: ["TASK_UPDATE"],
    defaultEnabled: true,
    ownedBy: "none",
  },
]);

const { statistics } = await client.getStatistics();

Errors & retries

Failed responses throw typed errors with code, message, and requestId. The client retries transient failures and respects Retry-After on rate_limited.

Error handlingts

import { WePeopleApiError } from "@wepeople/sdk";

try {
  await client.ingestEvents(events);
} catch (err) {
  if (err instanceof WePeopleApiError) {
    if (err.code === "forbidden_event_type") {
      // fix whitelist in Developer settings
    }
    console.error(err.requestId, err.docsUrl);
  }
  throw err;
}