@ranwhenparked/trustap-sdk 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# @ranwhenparked/trustap-sdk
+
+A lightweight typed [Trustap API](https://docs.trustap.com/apis/openapi) wrapper built with openapi-typescript + openapi-fetch.
+
+## Installation
+
+```bash
+npm install @ranwhenparked/trustap-sdk
+```
+
+## Usage
+
+### Path-based client
+
+```ts
+import { createTrustapClient } from "@ranwhenparked/trustap-sdk";
+
+const trustap = createTrustapClient({
+  apiUrl: process.env.TRUSTAP_API_URL!,
+  basicAuth: {
+    username: process.env.TRUSTAP_API_KEY!,
+    password: "", // Trustap basic auth uses API key + empty password
+  },
+});
+
+const { data, error } = await trustap["/users/me/balances"].GET({
+  headers: { Authorization: `Bearer ${accessToken}` },
+});
+
+// Or verb-based via raw
+const { data: d2 } = await trustap.raw.GET("/users/me/balances", {
+  headers: { Authorization: `Bearer ${accessToken}` },
+});
+```
+
+### Operation ID-based client
+
+Call API methods directly by their operation ID with full type safety:
+
+```ts
+const { data, error } = await trustap["users.getBalances"]();
+
+// With path parameters
+const { data: tx } = await trustap["basic_client.getTransaction"]({
+  params: {
+    path: { client_id: "my-client", transaction_id: "123" },
+  },
+});
+
+// With query parameters
+const { data: transactions } = await trustap["basic_client.getTransactions"]({
+  params: {
+    path: { client_id: "my-client" },
+    query: { status: "paid" },
+  },
+});
+```
+
+## Authentication
+
+The SDK supports multiple authentication strategies:
+
+### Basic Auth (Server-to-server)
+
+Configure HTTP Basic auth for server-to-server endpoints:
+
+```ts
+const trustap = createTrustapClient({
+  apiUrl: "https://api.trustap.com",
+  basicAuth: {
+    username: process.env.TRUSTAP_API_KEY!,
+    password: "", // Trustap uses API key + empty password
+  },
+});
+```
+
+### OAuth2 Access Token
+
+For user-context endpoints, provide a `getAccessToken` callback:
+
+```ts
+const trustap = createTrustapClient({
+  apiUrl: "https://api.trustap.com",
+  basicAuth: {
+    username: process.env.TRUSTAP_API_KEY!,
+    password: "",
+  },
+  getAccessToken: async () => {
+    // Return the current user's OAuth2 access token
+    return session.accessToken;
+  },
+});
+```
+
+The SDK automatically selects the correct auth strategy per endpoint based on the OpenAPI spec. For endpoints that support both, it prefers Basic auth for server-to-server calls.
+
+### Auth Overrides
+
+Override the automatic auth selection for specific endpoints:
+
+```ts
+const trustap = createTrustapClient({
+  apiUrl: "https://api.trustap.com",
+  basicAuth: { username: apiKey, password: "" },
+  getAccessToken: async () => userAccessToken,
+  authOverrides: {
+    "/charge": "basic",           // Always use Basic auth
+    "/users/me/balances": "oauth2", // Always use OAuth2
+  },
+});
+```
+
+## Webhook Schemas
+
+Validate incoming Trustap webhooks with Zod schemas:
+
+```ts
+import {
+  trustapWebhookEventSchema,
+  type TrustapWebhookEvent,
+} from "@ranwhenparked/trustap-sdk";
+
+// Parse and validate webhook payload
+const result = trustapWebhookEventSchema.safeParse(req.body);
+if (!result.success) {
+  console.error("Invalid webhook:", result.error);
+  return;
+}
+
+const event: TrustapWebhookEvent = result.data;
+console.log(event.code); // e.g., "basic_tx.paid"
+```
+
+### Exhaustive Handler Pattern
+
+Use `createWebhookHandlers` for compile-time exhaustiveness checking:
+
+```ts
+import {
+  createWebhookHandlers,
+  type TrustapWebhookEvent,
+} from "@ranwhenparked/trustap-sdk";
+
+const handlers = createWebhookHandlers({
+  "basic_tx.joined": (event) => {
+    console.log("Transaction joined at:", event.target_preview.joined);
+  },
+  "basic_tx.paid": (event) => {
+    console.log("Transaction paid at:", event.target_preview.paid);
+  },
+  "basic_tx.rejected": (event) => { /* ... */ },
+  "basic_tx.cancelled": (event) => { /* ... */ },
+  "basic_tx.claimed": (event) => { /* ... */ },
+  "basic_tx.listing_transaction_accepted": (event) => { /* ... */ },
+  "basic_tx.listing_transaction_rejected": (event) => { /* ... */ },
+  "basic_tx.payment_failed": (event) => { /* ... */ },
+  "basic_tx.payment_refunded": (event) => { /* ... */ },
+  "basic_tx.payment_review_flagged": (event) => { /* ... */ },
+  "basic_tx.payment_review_finished": (event) => { /* ... */ },
+  "basic_tx.tracking_details_submission_deadline_extended": (event) => { /* ... */ },
+  "basic_tx.tracked": (event) => { /* ... */ },
+  "basic_tx.delivered": (event) => { /* ... */ },
+  "basic_tx.complained": (event) => { /* ... */ },
+  "basic_tx.complaint_period_ended": (event) => { /* ... */ },
+  "basic_tx.funds_released": (event) => { /* ... */ },
+  "basic_tx.funds_refunded": (event) => { /* ... */ },
+});
+
+// TypeScript will error if any event code is missing from handlers
+
+function handleWebhook(event: TrustapWebhookEvent) {
+  const handler = handlers[event.code];
+  handler(event as never);
+}
+```
+
+### Individual Event Types
+
+Import specific event types for targeted handling:
+
+```ts
+import type {
+  BasicTxPaidEvent,
+  BasicTxFundsReleasedEvent,
+} from "@ranwhenparked/trustap-sdk";
+```
+
+## State Machine
+
+Map webhook events to transaction states:
+
+```ts
+import {
+  mapWebhookToTrustapState,
+  type TrustapTransactionState,
+} from "@ranwhenparked/trustap-sdk";
+
+const state = mapWebhookToTrustapState("basic_tx.paid");
+// state: "paid"
+
+const unknown = mapWebhookToTrustapState("unknown.event");
+// unknown: null
+```
+
+### Available States
+
+```ts
+type TrustapTransactionState =
+  | "created"
+  | "joined"
+  | "rejected"
+  | "paid"
+  | "cancelled"
+  | "cancelled_with_payment"
+  | "payment_refunded"
+  | "tracked"
+  | "delivered"
+  | "complained"
+  | "complaint_period_ended"
+  | "funds_released";
+```
+
+## Deno
+
+For Deno projects, import from the Deno-specific entry point:
+
+```ts
+import { createTrustapClient } from "@ranwhenparked/trustap-sdk/deno";
+```
+
+## Development
+
+### Generate types from OpenAPI spec
+
+```bash
+npm run generate
+```
+
+This pulls the latest OpenAPI schema from `https://docs.trustap.com/apis/trustap-openapi.yaml` and generates:
+
+- `src/schema.d.ts` - TypeScript types for all API paths and operations
+- `src/operations-map.ts` - Mapping of operation IDs to paths/methods
+- `src/security-map.ts` - Security requirements per endpoint
+
+Individual generation scripts:
+
+```bash
+npm run generate:types    # Generate schema.d.ts
+npm run generate:ops      # Generate operations-map.ts
+npm run generate:security # Generate security-map.ts
+```

package/deno.json

@@ -0,0 +1,9 @@
+{
+  "imports": {
+    "@std/assert": "jsr:@std/assert@^1"
+  },
+  "compilerOptions": {
+    "lib": ["deno.window", "dom"],
+    "strict": true
+  }
+}

package/eslint.config.js

@@ -0,0 +1,21 @@
+import baseConfig from "@rwp/eslint-config/base";
+
+/** @type {import('typescript-eslint').Config} */
+export default [
+  {
+    ignores: [
+      "dist/**",
+      "scripts/**",
+      "src/schema.d.ts",
+      "src/__tests__/deno/**",
+    ],
+  },
+  ...baseConfig,
+  {
+    files: ["src/**/*.{ts,tsx}"],
+    rules: {
+      "sonarjs/function-return-type": "error",
+    },
+  },
+];
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ranwhenparked/trustap-sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "deno": "./src/index.deno.ts",
+      "node": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./deno": "./src/index.deno.ts",
+    "./node": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node scripts/build-node.mjs",
+    "clean": "git clean -xdf .cache .turbo dist node_modules",
+    "format": "prettier --check . --ignore-path ../../.gitignore",
+    "lint": "eslint --fix --cache --cache-location .cache/.eslintcache",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false",
+    "generate:types": "npx openapi-typescript https://docs.trustap.com/apis/trustap-openapi.yaml -o src/schema.d.ts",
+    "generate:ops": "node ./scripts/generate-operations-map.mjs",
+    "generate:security": "node ./scripts/generate-security-map.mjs https://docs.trustap.com/apis/trustap-openapi.yaml",
+    "generate": "npm run generate:types && npm run generate:ops && npm run generate:security"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.15.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.39.2",
+    "openapi-typescript": "^7.10.1",
+    "prettier": "^3.8.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^3.2.4",
+    "yaml": "^2.8.2"
+  }
+}

package/scripts/build-node.mjs

@@ -0,0 +1,75 @@
+/**
+ * Build script for Node.js output.
+ *
+ * This script handles the dual-runtime extension problem:
+ * - Source files use .ts extensions (for Deno compatibility)
+ * - Node.js ESM needs .js extensions
+ * - TypeScript's tsc can't emit when sources have .ts extensions
+ *
+ * Solution:
+ * 1. Temporarily rewrite .ts → .js in source files
+ * 2. Run tsc to compile
+ * 3. Restore original .ts extensions in source files
+ * 4. Copy schema.d.ts to dist
+ */
+import { execFileSync } from "node:child_process";
+import { readFile, writeFile, copyFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const srcDir = join(__dirname, "..", "src");
+const distDir = join(__dirname, "..", "dist");
+
+const filesToProcess = ["index.ts", "client-factory.ts"];
+
+async function rewriteExtensions(files, from, to) {
+  for (const file of files) {
+    const filePath = join(srcDir, file);
+    let content = await readFile(filePath, "utf-8");
+
+    // Rewrite import/export extensions
+    const fromPattern = new RegExp(`from\\s+["'](\\.[^"']+)\\${from}["']`, "g");
+    content = content.replace(fromPattern, `from "$1${to}"`);
+
+    await writeFile(filePath, content);
+  }
+}
+
+async function build() {
+  console.log("1. Rewriting .ts → .js extensions in source files...");
+  await rewriteExtensions(filesToProcess, ".ts", ".js");
+  await rewriteExtensions(filesToProcess, ".d.ts", ".js");
+
+  try {
+    console.log("2. Compiling with tsc...");
+    execFileSync("npm", ["exec", "tsc", "-p", "tsconfig.build.json"], {
+      cwd: join(__dirname, ".."),
+      stdio: "inherit",
+    });
+
+    console.log("3. Copying schema.d.ts to dist...");
+    await copyFile(join(srcDir, "schema.d.ts"), join(distDir, "schema.d.ts"));
+
+    console.log("Build complete!");
+  } finally {
+    console.log("4. Restoring .ts extensions in source files...");
+    await rewriteExtensions(filesToProcess, ".js", ".ts");
+
+    // Also restore .d.ts for schema imports
+    for (const file of filesToProcess) {
+      const filePath = join(srcDir, file);
+      let content = await readFile(filePath, "utf-8");
+      content = content.replace(
+        /from\s+["']\.\/schema\.ts["']/g,
+        'from "./schema.d.ts"',
+      );
+      await writeFile(filePath, content);
+    }
+  }
+}
+
+build().catch((err) => {
+  console.error("Build failed:", err);
+  process.exit(1);
+});

package/scripts/generate-operations-map.mjs

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import yaml from "yaml";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+const OUTPUT = path.join(ROOT, "src", "operations-map.ts");
+
+async function main() {
+  const res = await fetch("https://docs.trustap.com/_spec/apis/openapi.yaml");
+  if (!res.ok) throw new Error(`Failed to fetch OpenAPI: ${res.status}`);
+  const text = await res.text();
+  const doc = yaml.parse(text);
+
+  const opToPath = {};
+  for (const [p, methods] of Object.entries(doc.paths ?? {})) {
+    for (const [method, op] of Object.entries(methods)) {
+      if (!op || typeof op !== "object") continue;
+      const id = op.operationId;
+      if (!id) continue;
+      opToPath[id] = { path: p, method: method.toUpperCase() };
+    }
+  }
+
+  const overrideOperations = {
+    "basic.createTransaction": { path: "/transactions", method: "POST" },
+    "basic.getTransactions": { path: "/transactions", method: "GET" },
+  };
+
+  for (const [key, value] of Object.entries(overrideOperations)) {
+    opToPath[key] = value;
+  }
+
+  const additionalOperations = {
+    "oauth.getUser": { path: "/users/{userId}", method: "GET" },
+    "oauth.updateUser": { path: "/users/{userId}", method: "PUT" },
+  };
+
+  for (const [key, value] of Object.entries(additionalOperations)) {
+    if (!opToPath[key]) {
+      opToPath[key] = value;
+    }
+  }
+
+  const file = `// generated by scripts/generate-operations-map.mjs\n` +
+    `export const operationIdToPath = ${JSON.stringify(opToPath, null, 2)} as const;\n`;
+
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, file);
+  console.log(`Wrote ${OUTPUT}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/generate-security-map.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// Generate a minimal security map from an OpenAPI document (JSON or YAML)
+// Usage: node scripts/generate-security-map.mjs [/absolute/or/relative/path/or/url]
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+let YAML;
+try {
+  YAML = require('yaml');
+} catch {}
+
+const inputArg = process.argv[2] || 'https://docs.trustap.com/_spec/apis/openapi.yaml';
+
+async function readOpenApi(source) {
+  if (/^https?:\/\//.test(source)) {
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`Failed to fetch ${source}: ${res.status}`);
+    const text = await res.text();
+    if (source.endsWith('.yaml') || source.endsWith('.yml')) {
+      if (!YAML) throw new Error('yaml package not available');
+      return YAML.parse(text);
+    }
+    return JSON.parse(text);
+  }
+  const content = fs.readFileSync(source, 'utf8');
+  if (source.endsWith('.yaml') || source.endsWith('.yml')) {
+    if (!YAML) throw new Error('yaml package not available');
+    return YAML.parse(content);
+  }
+  return JSON.parse(content);
+}
+
+function normalizeSecurityArray(secArr) {
+  // Convert OpenAPI security array to a set of scheme names
+  // e.g., [{ OAuth2: [] }, { APIKey: [] }] -> Set(['OAuth2','APIKey'])
+  const set = new Set();
+  if (Array.isArray(secArr)) {
+    for (const entry of secArr) {
+      if (entry && typeof entry === 'object') {
+        for (const key of Object.keys(entry)) set.add(key);
+      }
+    }
+  }
+  return set;
+}
+
+function buildSecurityMap(doc) {
+  const out = {}; // { path: { METHOD: ['APIKey','OAuth2'] } }
+  const globalSec = normalizeSecurityArray(doc.security);
+  const paths = doc.paths || {};
+  for (const p of Object.keys(paths)) {
+    const item = paths[p] || {};
+    for (const method of Object.keys(item)) {
+      const op = item[method];
+      if (!op || typeof op !== 'object') continue;
+      if (!['get','post','put','patch','delete','head','options','trace'].includes(method)) continue;
+      const opSec = normalizeSecurityArray(op.security);
+      const effective = opSec.size > 0 ? opSec : globalSec;
+      if (!out[p]) out[p] = {};
+      out[p][method.toUpperCase()] = Array.from(effective);
+    }
+  }
+  return out;
+}
+
+function emitTs(securityMap) {
+  const header = `// generated by scripts/generate-security-map.mjs\n`;
+  const body = `export const securityMap = ${JSON.stringify(securityMap, null, 2)} as const;\n`;
+  return header + body;
+}
+
+async function main() {
+  const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const outFile = path.join(rootDir, 'src', 'security-map.ts');
+  const api = await readOpenApi(inputArg);
+  const map = buildSecurityMap(api);
+  const ts = emitTs(map);
+  fs.writeFileSync(outFile, ts, 'utf8');
+  console.log(`Wrote ${outFile}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+
+