@ranwhenparked/trustap-sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,251 +1,215 @@
-# @ranwhenparked/trustap-sdk
+# trustap-sdk
 
-A lightweight typed [Trustap API](https://docs.trustap.com/apis/openapi) wrapper built with openapi-typescript + openapi-fetch.
+[![npm version](https://img.shields.io/npm/v/@ranwhenparked/trustap-sdk.svg)](https://www.npmjs.com/package/@ranwhenparked/trustap-sdk)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-## Installation
-
-```bash
-npm install @ranwhenparked/trustap-sdk
-```
+Type-safe TypeScript SDK for the [Trustap API](https://trustap.com) with webhook validation.
 
-## Usage
+## Overview
 
-### Path-based client
+Trustap provides escrow and payment protection for peer-to-peer and marketplace transactions. This SDK offers:
 
-```ts
-import { createTrustapClient } from "@ranwhenparked/trustap-sdk";
+- **Type-safe API client** built on [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) with auto-generated types
+- **Webhook validation** using Zod schemas with TypeScript exhaustiveness checking
+- **Transaction state machine** for tracking transaction lifecycle
+- **Dual runtime support** for Node.js and Deno
 
-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
-  },
-});
+## Installation
 
-const { data, error } = await trustap["/users/me/balances"].GET({
-  headers: { Authorization: `Bearer ${accessToken}` },
-});
+```bash
+npm install trustap-sdk
+```
 
-// Or verb-based via raw
-const { data: d2 } = await trustap.raw.GET("/users/me/balances", {
-  headers: { Authorization: `Bearer ${accessToken}` },
-});
+```bash
+yarn add trustap-sdk
 ```
 
-### Operation ID-based client
+```bash
+pnpm add trustap-sdk
+```
 
-Call API methods directly by their operation ID with full type safety:
+## Quick Start
 
-```ts
-const { data, error } = await trustap["users.getBalances"]();
+```typescript
+import { createTrustapClient, TRUSTAP_BASE_URLS } from "trustap-sdk";
 
-// With path parameters
-const { data: tx } = await trustap["basic_client.getTransaction"]({
-  params: {
-    path: { client_id: "my-client", transaction_id: "123" },
-  },
+const client = createTrustapClient({
+  baseUrl: TRUSTAP_BASE_URLS.production,
+  auth: { type: "apiKey", apiKey: "your-api-key" },
 });
 
-// With query parameters
-const { data: transactions } = await trustap["basic_client.getTransactions"]({
+// Calculate transaction fees
+const { data, error } = await client.GET("/charge", {
   params: {
-    path: { client_id: "my-client" },
-    query: { status: "paid" },
+    query: { price: 10000, currency: "USD" },
   },
 });
 ```
 
 ## Authentication
 
-The SDK supports multiple authentication strategies:
-
-### Basic Auth (Server-to-server)
+### API Key (Server-side)
 
-Configure HTTP Basic auth for server-to-server endpoints:
+Use API key authentication for server-to-server requests:
 
-```ts
-const trustap = createTrustapClient({
-  apiUrl: "https://api.trustap.com",
-  basicAuth: {
-    username: process.env.TRUSTAP_API_KEY!,
-    password: "", // Trustap uses API key + empty password
-  },
+```typescript
+const client = createTrustapClient({
+  auth: { type: "apiKey", apiKey: process.env.TRUSTAP_API_KEY },
 });
 ```
 
-### OAuth2 Access Token
+### OAuth (User-authenticated)
 
-For user-context endpoints, provide a `getAccessToken` callback:
+Use OAuth for requests on behalf of authenticated users:
 
-```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;
-  },
+```typescript
+const client = createTrustapClient({
+  auth: { type: "oauth", accessToken: userAccessToken },
 });
 ```
 
-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.
+## Client Usage
 
-### Auth Overrides
+### Standard Client
 
-Override the automatic auth selection for specific endpoints:
+```typescript
+import { createTrustapClient } from "trustap-sdk";
 
-```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
-  },
+const client = createTrustapClient({
+  baseUrl: TRUSTAP_BASE_URLS.staging, // or .production
+  auth: { type: "apiKey", apiKey: "..." },
 });
+
+// Fully typed request/response
+const { data, error } = await client.GET("/me/transactions");
 ```
 
-## Webhook Schemas
+### Path-based Client
 
-Validate incoming Trustap webhooks with Zod schemas:
+```typescript
+import { createTrustapPathClient } from "trustap-sdk";
 
-```ts
-import {
-  trustapWebhookEventSchema,
-  type TrustapWebhookEvent,
-} from "@ranwhenparked/trustap-sdk";
+const client = createTrustapPathClient({ /* options */ });
 
-// Parse and validate webhook payload
-const result = trustapWebhookEventSchema.safeParse(req.body);
-if (!result.success) {
-  console.error("Invalid webhook:", result.error);
-  return;
-}
+// Alternative syntax
+const { data } = await client["/me/transactions"].GET();
+```
 
-const event: TrustapWebhookEvent = result.data;
-console.log(event.code); // e.g., "basic_tx.paid"
+### Environments
+
+```typescript
+import { TRUSTAP_BASE_URLS } from "trustap-sdk";
+
+TRUSTAP_BASE_URLS.staging    // https://dev.stage.trustap.com/api/v1
+TRUSTAP_BASE_URLS.production // https://dev.trustap.com/api/v1
+```
+
+## Webhook Handling
+
+### Parsing Events
+
+```typescript
+import { trustapWebhookEventSchema } from "trustap-sdk";
+
+async function handleWebhook(req: Request) {
+  const body = await req.json();
+  const result = trustapWebhookEventSchema.safeParse(body);
+
+  if (!result.success) {
+    // Unknown or malformed event - fails loudly, no silent fallbacks
+    console.error("Invalid webhook:", result.error);
+    return;
+  }
+
+  const event = result.data;
+  // event.code is narrowed to specific event types
+}
 ```
 
-### Exhaustive Handler Pattern
+### Type-safe Handlers
 
-Use `createWebhookHandlers` for compile-time exhaustiveness checking:
+Create handlers with compile-time exhaustiveness checking:
 
-```ts
-import {
-  createWebhookHandlers,
-  type TrustapWebhookEvent,
-} from "@ranwhenparked/trustap-sdk";
+```typescript
+import { createOnlineWebhookHandlers, type TrustapWebhookEvent } from "trustap-sdk";
 
-const handlers = createWebhookHandlers({
+const handlers = createOnlineWebhookHandlers({
   "basic_tx.joined": (event) => {
-    console.log("Transaction joined at:", event.target_preview.joined);
+    console.log("Seller joined:", event.target_preview.joined);
   },
   "basic_tx.paid": (event) => {
-    console.log("Transaction paid at:", event.target_preview.paid);
+    console.log("Payment received:", event.target_preview.paid);
+  },
+  "basic_tx.tracked": (event) => {
+    console.log("Tracking:", event.target_preview.tracking);
   },
-  "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 errors if any event type is missing
+  // ... all 18 event types must be handled
 });
 
-// TypeScript will error if any event code is missing from handlers
-
-function handleWebhook(event: TrustapWebhookEvent) {
-  const handler = handlers[event.code];
-  handler(event as never);
+function processEvent(event: TrustapWebhookEvent) {
+  handlers[event.code](event as any);
 }
 ```
 
-### Individual Event Types
-
-Import specific event types for targeted handling:
-
-```ts
-import type {
-  BasicTxPaidEvent,
-  BasicTxFundsReleasedEvent,
-} from "@ranwhenparked/trustap-sdk";
+### Switch with Exhaustiveness
+
+```typescript
+import { assertNever, type TrustapWebhookEvent } from "trustap-sdk";
+
+function handleEvent(event: TrustapWebhookEvent) {
+  switch (event.code) {
+    case "basic_tx.joined":
+      return handleJoined(event);
+    case "basic_tx.paid":
+      return handlePaid(event);
+    // ... handle all cases
+    default:
+      assertNever(event); // Compile error if any case is missing
+  }
+}
 ```
 
-## State Machine
+### State Machine
 
 Map webhook events to transaction states:
 
-```ts
-import {
-  mapWebhookToTrustapState,
-  type TrustapTransactionState,
-} from "@ranwhenparked/trustap-sdk";
+```typescript
+import { mapWebhookToOnlineState } from "trustap-sdk";
 
-const state = mapWebhookToTrustapState("basic_tx.paid");
-// state: "paid"
-
-const unknown = mapWebhookToTrustapState("unknown.event");
-// unknown: null
+const state = mapWebhookToOnlineState("basic_tx.paid");
+// Returns: "paid"
 ```
 
-### Available States
-
-```ts
-type TrustapTransactionState =
-  | "created"
-  | "joined"
-  | "rejected"
-  | "paid"
-  | "cancelled"
-  | "cancelled_with_payment"
-  | "payment_refunded"
-  | "tracked"
-  | "delivered"
-  | "complained"
-  | "complaint_period_ended"
-  | "funds_released";
-```
+## Subpath Imports
 
-## Deno
+Import only what you need:
 
-For Deno projects, import from the Deno-specific entry point:
+```typescript
+// Full SDK
+import { createTrustapClient, trustapWebhookEventSchema } from "trustap-sdk";
 
-```ts
-import { createTrustapClient } from "@ranwhenparked/trustap-sdk/deno";
+// Webhooks only (smaller bundle)
+import { trustapWebhookEventSchema, createOnlineWebhookHandlers } from "trustap-sdk/webhooks";
+
+// Types only (no runtime code)
+import type { paths, components } from "trustap-sdk/types";
 ```
 
-## Development
+## Deno
 
-### Generate types from OpenAPI spec
+```typescript
+import { createTrustapClient } from "./mod.ts";
 
-```bash
-npm run generate
+// Or from npm
+import { createTrustapClient } from "npm:trustap-sdk";
 ```
 
-This pulls the latest OpenAPI schema from `https://docs.trustap.com/apis/trustap-openapi.yaml` and generates:
+## API Reference
 
-- `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
+This SDK's types are auto-generated from the [Trustap OpenAPI specification](https://docs.trustap.com). For endpoint documentation, see the [Trustap API docs](https://docs.trustap.com).
 
-Individual generation scripts:
+## License
 
-```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
-```
+ISC

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import { type Client, type ClientOptions, type PathBasedClient } from "openapi-fetch";
+import type { paths } from "./generated/types.ts";
+export declare const TRUSTAP_BASE_URLS: {
+    readonly staging: "https://dev.stage.trustap.com/api/v1";
+    readonly production: "https://dev.trustap.com/api/v1";
+};
+export type TrustapClient = Client<paths>;
+export type TrustapPathClient = PathBasedClient<paths>;
+export type TrustapAuth = {
+    type: "apiKey";
+    apiKey: string;
+} | {
+    type: "oauth";
+    accessToken: string;
+};
+export type TrustapClientOptions = Omit<ClientOptions, "baseUrl" | "headers"> & {
+    baseUrl?: string;
+    headers?: ClientOptions["headers"];
+    auth?: TrustapAuth;
+};
+export declare function createApiKeyAuthHeader(apiKey: string): string;
+export declare function createBearerAuthHeader(accessToken: string): string;
+export declare function createTrustapClient(options?: TrustapClientOptions): TrustapClient;
+export declare function createTrustapPathClient(options?: TrustapClientOptions): TrustapPathClient;

package/dist/client.js

@@ -0,0 +1,66 @@
+import createClient, { createPathBasedClient, mergeHeaders, } from "openapi-fetch";
+export const TRUSTAP_BASE_URLS = {
+    staging: "https://dev.stage.trustap.com/api/v1",
+    production: "https://dev.trustap.com/api/v1",
+};
+export function createApiKeyAuthHeader(apiKey) {
+    return `Basic ${encodeBase64(`${apiKey}:`)}`;
+}
+export function createBearerAuthHeader(accessToken) {
+    return `Bearer ${accessToken}`;
+}
+export function createTrustapClient(options = {}) {
+    const { baseUrl = TRUSTAP_BASE_URLS.staging, headers, auth, ...rest } = options;
+    const authHeader = resolveAuthHeader(auth);
+    const clientOptions = { baseUrl, ...rest };
+    if (authHeader) {
+        clientOptions.headers = withAuthHeader(headers, authHeader);
+    }
+    else if (headers) {
+        clientOptions.headers = headers;
+    }
+    return createClient(clientOptions);
+}
+export function createTrustapPathClient(options = {}) {
+    const { baseUrl = TRUSTAP_BASE_URLS.staging, headers, auth, ...rest } = options;
+    const authHeader = resolveAuthHeader(auth);
+    const clientOptions = { baseUrl, ...rest };
+    if (authHeader) {
+        clientOptions.headers = withAuthHeader(headers, authHeader);
+    }
+    else if (headers) {
+        clientOptions.headers = headers;
+    }
+    return createPathBasedClient(clientOptions);
+}
+function resolveAuthHeader(auth) {
+    if (!auth)
+        return undefined;
+    return auth.type === "apiKey"
+        ? createApiKeyAuthHeader(auth.apiKey)
+        : createBearerAuthHeader(auth.accessToken);
+}
+function withAuthHeader(headers, value) {
+    return mergeHeaders(headers, { Authorization: value });
+}
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function encodeBase64(input) {
+    if (typeof globalThis.btoa === "function") {
+        return globalThis.btoa(input);
+    }
+    const bytes = new TextEncoder().encode(input);
+    let output = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b1 = bytes[i] ?? 0;
+        const b2 = bytes[i + 1] ?? 0;
+        const b3 = bytes[i + 2] ?? 0;
+        const hasB2 = i + 1 < bytes.length;
+        const hasB3 = i + 2 < bytes.length;
+        const triplet = (b1 << 16) | (b2 << 8) | b3;
+        output += BASE64_ALPHABET[(triplet >> 18) & 0x3f];
+        output += BASE64_ALPHABET[(triplet >> 12) & 0x3f];
+        output += hasB2 ? BASE64_ALPHABET[(triplet >> 6) & 0x3f] : "=";
+        output += hasB3 ? BASE64_ALPHABET[triplet & 0x3f] : "=";
+    }
+    return output;
+}