@tesser-payments/types

Shared TypeScript types and Zod schemas for the Tesser Payments platform. This package provides a single source of truth for type definitions used across both backend and frontend applications.

📁 Structure

The package is organized by domain:

src/
├── common/           # Shared utilities and types
│   ├── currency.ts
│   ├── validations.ts
│   ├── pagination.ts
│   └── api-response.ts
├── payments/         # Payment-related types
│   ├── payment.types.ts
│   └── payment.schemas.ts
├── entities/         # Entity management types
│   ├── entity.types.ts
│   └── entity.schemas.ts
├── wallets/          # Wallet and account types
│   ├── wallet.types.ts
│   └── wallet.schemas.ts
├── accounts/         # Fiat account types
│   ├── account.types.ts
│   └── account.schemas.ts
├── ramps/            # Onramp/Offramp types
│   ├── ramp.types.ts
│   └── ramp.schemas.ts
├── apps/             # App management types
│   ├── app.types.ts
│   └── app.schemas.ts
├── organizations/    # Organization types
│   ├── organization.types.ts
│   └── organization.schemas.ts
├── users/            # User management types
│   ├── user.types.ts
│   └── user.schemas.ts
└── webhooks/         # Webhook types
    ├── webhook.types.ts
    └── webhook.schemas.ts

🚀 Usage

Frontend Usage (Type Imports Only)

Import TypeScript types for type-checking:

import type { PaymentDto, PaymentStatus } from "@tesser-payments/types/payments";
import type { PaginationInfo } from "@tesser-payments/types/common";

Frontend Usage (With Validation)

Import Zod schemas for runtime validation:

import {
  sendPaymentIntentRequestSchema,
  type SendPaymentIntentDto,
} from "@tesser-payments/types/payments";

// Use schema for validation
const result = sendPaymentIntentRequestSchema.safeParse(data);
if (result.success) {
  // data is valid
}

Backend Usage (NestJS DTOs)

Import schemas and create NestJS DTOs:

import { sendPaymentIntentRequestSchema } from "@tesser-payments/types/payments";
import { createZodDto } from "nestjs-zod";

export class SendPaymentIntentRequestDto extends createZodDto(
  sendPaymentIntentRequestSchema
) {}

📦 Available Domains

Common (@tesser-payments/types/common)

• Currency utilities (SupportedCurrency, conversion functions)
• Payment limits
• Validation utilities (isIBAN, validateEmail, etc.)
• Pagination types (PaginationInfo, PaginatedResponse)
• API response wrappers (ApiResponse, ApiSuccessResponse)

Payments (@tesser-payments/types/payments)

• PaymentDto - Full payment object
• PaymentStatus - Payment status enum
• SendPaymentIntentDto - Payment intent request
• SendPaymentDto - Send payment request
• Related schemas

Entities (@tesser-payments/types/entities)

• EntityDto - Entity details
• EntityType - Entity type enum
• CreateEntityDto - Create request
• UpdateEntityDto - Update request
• Related schemas

Wallets (@tesser-payments/types/wallets)

• WalletDto - Wallet details
• WalletQueryDto - Query parameters
• Related schemas

Accounts (@tesser-payments/types/accounts)

• FiatAccountDto - Fiat account details
• AccountType - Account type enum ("PIX" | "SPEI" | "COELSA")
• createFiatAccountRequestSchema - Base schema for fiat account creation (KYB endpoint)
• createFiatAccountWithEntitySchema - Extended schema with entityId (Entities endpoint)
• CreateFiatAccountRequest - Inferred type from base schema
• CreateFiatAccountWithEntity - Inferred type from extended schema

See Schema Guidelines below for usage details.

Ramps (@tesser-payments/types/ramps)

• Onramp/Offramp transaction types
• Quote request types
• Alfred-specific types
• Status enums
• Related schemas

Apps (@tesser-payments/types/apps)

• AppDto - App details
• CreateAppDto - Create request
• Related schemas

Organizations (@tesser-payments/types/organizations)

• RiskProfileDto - Risk profile details
• UpdateRiskProfileDto - Update request
• Related schemas

Users (@tesser-payments/types/users)

• UserProfileDto - User profile
• SignupRequest / SignupResponse - Signup flow
• OrgUserDto - Organization user
• Related schemas

Webhooks (@tesser-payments/types/webhooks)

• WebhookPaymentDto - Webhook payload
• WebhookEventType - Event type enum
• WebhookEvent - Event structure
• Related schemas

🎯 Design Principles

1. Single Source of Truth: All types defined once, used everywhere
2. Domain Organization: Types grouped by business domain for easy navigation
3. Dual Exports: Both TypeScript types and Zod schemas available
4. Framework Agnostic: Core types don't depend on NestJS or React
5. Tree Shakeable: Import only what you need
6. Schema Consistency: Shared base schemas prevent validation mismatches

📋 Schema Guidelines

Fiat Account Creation

Two endpoint-specific schemas are provided, both extending a unified base:

// For KYB endpoint (POST /kyb/fiat-accounts)
import { createFiatAccountRequestSchema } from "@tesser-payments/types/accounts";

// For Entities endpoint (POST /entities/fiat-accounts)
import { createFiatAccountWithEntitySchema } from "@tesser-payments/types/accounts";

Key differences:

• createFiatAccountRequestSchema: Standard fiat account creation
• createFiatAccountWithEntitySchema: Includes optional entityId field for linking to entities

Common validation rules:

• provider: Must be "ALFRED"
• country: 2-character country code
• accountType: "PIX" | "SPEI" | "COELSA"
• accountNumber: Required, min 1 character
• accountDetails: Structured object with accountType and financialInstitutionID
• isExternal: Optional boolean, defaults to false
• externalId: Optional string for client-provided identifiers

🔄 Type Safety Guarantees

• Backend DTOs use the same schemas as frontend validation
• API contracts automatically propagate to both sides
• Validation rules stay in sync
• Compile-time errors catch mismatches

🛠️ Development

Building

cd packages/types
bun run build

This compiles src/ to dist/ with TypeScript declarations and generates a publish-ready dist/package.json. Local development does not require building — Bun resolves the src/*.ts exports directly in the workspace.

Publishing to npm

The version is managed in packages/types/package.json (source of truth). Publishing is done via the Publish @tesser-payments/types GitHub Action (workflow_dispatch):

1. Bump the version in packages/types/package.json in a PR and merge to main
2. Go to Actions → Publish @tesser-payments/types → Run workflow
3. Optionally set the npm dist-tag (default: latest) and whether to dry-run
4. The action reads the version from package.json, checks that it hasn't already been published, builds, publishes to npm, and creates a types-v{version} git tag and GitHub release

The workflow will fail if the version in package.json is already published to npm — you must bump the version first.

Prerequisites:

• NPM_TOKEN repository secret must be configured in GitHub Settings → Secrets → Actions
• @tesser-payments npm org must exist with publish access

To preview locally what would be published:

cd packages/types
bun run build
cd dist
npm pack --dry-run

Adding New Types

1. Choose the appropriate domain directory (or create a new one)
2. Create *.types.ts for TypeScript interfaces
3. Create *.schemas.ts for Zod schemas and inferred types
4. Export from domain's index.ts
5. Update root src/index.ts if needed

Pattern to Follow

// my-domain/my-domain.types.ts
export interface MyDto {
  id: string;
  name: string;
}

// my-domain/my-domain.schemas.ts
import { z } from "zod";

export const mySchema = z.object({
  name: z.string().min(1),
});

export type MyCreateDto = z.infer<typeof mySchema>;

// my-domain/index.ts
export * from "./my-domain.types";
export * from "./my-domain.schemas";

📝 Migration Notes

This package was reorganized from a flat structure to domain-based organization. Legacy imports from the root still work but are deprecated:

// ❌ Deprecated (still works)
import { SupportedCurrency } from "@tesser-payments/types";

// ✅ Preferred
import type { SupportedCurrency } from "@tesser-payments/types/common";

🤝 Contributing

When adding or modifying types:

1. Ensure types match backend DTOs exactly
2. Include JSDoc comments for complex types
3. Export both schemas and inferred types
4. Update this README if adding new domains
5. Run type checks before committing

📚 Related Packages

• @tesser-payments/sdk - SDK using these types
• Backend (apps/backend) - NestJS backend consuming types
• Frontend (apps/frontend) - Next.js frontend consuming types