SDK Usage

Overview

The Syllecta SDK keeps client code small. It covers three needs:

Idempotency – sdk.idempotency.checkOrLock and sdk.idempotency.save.
Forward provider events – forwardWebhookEvent sends provider payloads to Syllecta.
Local dedupe – handleWebhookEvent guards your own handlers.

Install via npm install @syllecta/sdk-js (or pnpm/yarn). Then follow the steps below.

1. Create a client

import { CloudSDK } from "@syllecta/sdk-js";
 
export const syllecta = new CloudSDK({
  baseUrl: "https://cloud.syllecta.example",
  auth: { type: "bearer", token: process.env.SYLLECTA_API_KEY! }
});

2. Check/lock then save

const lock = await syllecta.idempotency.checkOrLock({
  scope: "orders",
  key: "order-2001"
});
 
if (lock.cached) {
  return lock.record;
}
 
if (!lock.locked) {
  throw new Error(`Retry after ${lock.retryAfterMs}ms`);
}
 
await syllecta.idempotency.save({
  scope: "orders",
  key: "order-2001",
  body: { status: "authorized" }
});

Possible responses

cached: true – record already exists, use it.
locked: true – safe to proceed and save.
locked: false – wait retryAfterMs and retry.
429 – usage limit exceeded.

3. Forward provider events

Use forwardWebhookEvent if you receive events in your own infrastructure and want Syllecta to handle dedupe + forwarding.

By default the helper authenticates to Syllecta with Authorization: Bearer <ck_...>. Only set a custom header in legacy/internal compatibility flows.

import { forwardWebhookEvent } from "@syllecta/sdk-js";
 
await forwardWebhookEvent({
  provider: "stripe",
  apiKey: process.env.SYLLECTA_API_KEY!,
  body: stripeEvent,
  headers: stripeHeaders,
  baseUrl: "https://cloud.syllecta.example"
});

4. Handle events locally

import { handleWebhookEvent } from "@syllecta/sdk-js";
 
await handleWebhookEvent({
  provider: "stripe",
  apiKey: process.env.SYLLECTA_API_KEY!,
  body: req.body,
  rawBody: req.rawBody,
  headers: {
    "stripe-signature": req.get("stripe-signature") ?? undefined
  },
  onProcess: async ({ body }) => {
    await billing.syncInvoice(body.data.invoiceId);
  },
  onDuplicate: () => logger.info("Ignoring replay")
});

5. Trigger chargeback simulations

const simulation = await syllecta.simulations.createChargeback({
  provider: "stripe",
  amount: 2500,
  currency: "usd",
  transactionId: "ch_demo_123",
  simulateLifecycle: true,
  finalStatus: "won"
});
 
console.log(simulation.simulation.id, simulation.simulation.status);