@ranwhenparked/trustap-sdk

Type-safe TypeScript SDK for Trustap API v2, generated from Trustap's OpenAPI specification and including Zod webhook validation.

Install

npm install @ranwhenparked/trustap-sdk

Client

import {
  createTrustapClient,
  TRUSTAP_BASE_URLS,
} from "@ranwhenparked/trustap-sdk";

const client = createTrustapClient({
  baseUrl: TRUSTAP_BASE_URLS.production,
  auth: { type: "apiKey", apiKey: process.env.TRUSTAP_API_KEY! },
});

const { data: fees, error } = await client.GET("/v2/fees", {
  params: { query: { amount: 10_000, currency: "eur" } },
});

The default environment is the sandbox. OAuth access tokens are also supported:

const client = createTrustapClient({
  auth: { type: "oauth", accessToken: userAccessToken },
});

Environments

TRUSTAP_BASE_URLS.sandbox;    // https://api.test.trustap.com
TRUSTAP_BASE_URLS.production; // https://api.trustap.com

The generated paths include the /v2 prefix, so custom baseUrl values should point to the host root.

Transactions

API v2 uses one transaction resource for shipped and face-to-face exchanges. Transaction IDs are globally unique strings prefixed with tx_.

if (!fees) throw new Error("Unable to calculate fees");

const { data: transaction } = await client.POST("/v2/transactions", {
  body: {
    role: "seller",
    description: "Trustap socks",
    currency: "eur",
    amount: 10_000,
    fees_buyer: fees.buyer,
    fees_seller: fees.seller,
    fees_config: fees.config,
    contains_shipping: true,
  },
});

console.log(transaction?.id); // tx_...
console.log(transaction?.pricing.amount);

A path-based client is also available:

import { createTrustapPathClient } from "@ranwhenparked/trustap-sdk";

const client = createTrustapPathClient();
const { data } = await client["/v2/transactions/{transaction_id}"].GET({
  params: { path: { transaction_id: "tx_..." } },
});

Webhooks

The webhook parser accepts the documented API v2 tx.* event codes and validates v2 transaction IDs and target previews. Unknown event codes fail validation.

import {
  mapWebhookToTransactionState,
  trustapWebhookEventSchema,
} from "@ranwhenparked/trustap-sdk/webhooks";

const result = trustapWebhookEventSchema.safeParse(await request.json());
if (!result.success) throw result.error;

const event = result.data;
console.log(event.code); // tx.paid
console.log(mapWebhookToTransactionState(event)); // paid, or null without a preview

Use createWebhookHandlers for an exhaustive handler map over all documented v2 event codes.

Types and subpath imports

import type { paths, components } from "@ranwhenparked/trustap-sdk/types";
import { trustapWebhookEventSchema } from "@ranwhenparked/trustap-sdk/webhooks";

Deno

import { createTrustapClient } from "./mod.ts";
// or: import { createTrustapClient } from "npm:@ranwhenparked/trustap-sdk";

API reference

• Trustap API v2 reference
• Upgrade guide

License

ISC