@moonlab-tech/earn-sdk

Type-safe SDK for consuming Velox Earn API endpoints using oRPC. This package provides complete TypeScript types and the oRPC contract to build type-safe API clients for external applications.

Installation

npm install @moonlab-tech/earn-sdk

# Or with pnpm
pnpm add @moonlab-tech/earn-sdk

Usage

Creating a Type-Safe oRPC Client

import { createORPCClient, type Client, contract } from '@moonlab-tech/earn-sdk';
import { OpenAPILink } from '@orpc/openapi-client/fetch';

const link = new OpenAPILink(contract as any, {
  url: 'https://your-velox-earn-api.com',
  fetch: async (request, options) => {
    const req = new Request(request, options);
    req.headers.set('Authorization', `Bearer ${yourAuthToken}`);
    return fetch(req);
  },
});

// Create a fully typed client with autocomplete for all API routes
export const client = createORPCClient<Client>(link).api;

// Now you have full type safety and autocomplete:
await client.profile.getV2();
await client.balance.getV2();
await client.transactions.getTransactions();
// ... and all other API endpoints

Available Exports

• Client - TypeScript type providing full route typing (from @jasonaviandres/velox-earn-types)
• contract - oRPC contract for creating API links
• createORPCClient - oRPC client factory (re-exported from @orpc/client)
• RouterClient - Type helper (re-exported from @orpc/server)

Packages

• @moonlab-tech/earn-sdk - Runtime SDK with contract and oRPC client utilities
• @moonlab-tech/velox-earn-types - TypeScript type definitions for full API type safety

TypeScript Support

The Client type is derived from the server's router definition (RouterClient<typeof routes>), providing:

• Full autocomplete for all API endpoints
• Type-safe request parameters
• Type-safe response types
• Compile-time error checking

import { createORPCClient, onError, type RouterClient } from '@moonlab-tech/earn-sdk';
import { OpenAPILink } from '@orpc/openapi-client/fetch';
import { contract } from '@moonlab-tech/earn-sdk/contract';

const link = new OpenAPILink(contract as any, {
  url: 'https://your-api-endpoint.com',
  fetch: async (request, options) => {
    // Add custom headers like authentication
    const req = new Request(request, options);
    req.headers.set('Authorization', `Bearer ${yourAuthToken}`);
    return fetch(req);
  },
  interceptors: [
    onError((error) => {
      console.error('API Error:', error);
    }),
  ],
});

// Create the typed client - types are inferred from the contract
export const client = createORPCClient<RouterClient<typeof contract>>(link).api;

Using the Client

The client provides full type safety for all API endpoints:

// Get user profile
const profile = await client.profile.getV2({});

// Get balance
const balance = await client.balance.getV2({});

// Create a deposit
const deposit = await client.transactions.depositV2({
  body: {
    amount: '100.00',
    currency: 'USD',
  },
});

// Get transactions with pagination
const transactions = await client.transactions.getTransactions({
  query: {
    cursor: undefined,
    pageSize: '20',
  },
});

Type Inference

Extract input and output types from the client:

import type { InferClientInputs, InferClientOutputs } from '@velox/earn-sdk';
import type { client } from './your-client-file';

type Inputs = InferClientInputs<typeof client>;
type Outputs = InferClientOutputs<typeof client>;

// Get specific endpoint types
export type GetProductsInput = Inputs['products']['get'];
export type ProductsOutput = Outputs['products']['get']['body'];

React Query Integration

Combine with React Query for data fetching:

import { queryOptions } from '@tanstack/react-query';
import { client } from './your-client-file';

export const profileQueryOpts = queryOptions({
  queryKey: ['profile'],
  queryFn: () => client.profile.getV2({}).then((d) => d.body),
});

// Use in component
function ProfileComponent() {
  const { data: profile } = useQuery(profileQueryOpts);
  return <div>{profile?.name}</div>;
}

Publishing Workflow (For Maintainers)

Prerequisites

1. Build the server first to generate the contract and types:

   cd apps/server
   pnpm run build:orpc

   This generates:

   • apps/server/dist/_orpc/contract.js - Runtime contract
   • apps/server/dist/_orpc/contract.d.ts - Contract types
   • apps/server/dist/src/index.d.ts - Client types

Build the SDK

2. Build the SDK package:

   cd packages/earn-sdk
   pnpm build

   The build process:

   • Runs prebuild script to copy server artifacts to src/generated/
   • Bundles the SDK with tsup
   • Outputs to dist/ with proper ESM format

Publish to GitHub Packages

3. Publish the package:

   cd packages/earn-sdk
   pnpm publish

   The package is configured to publish to GitHub Packages registry (https://npm.pkg.github.com).

Version Management

• SDK version should track the server API version
• Use semantic versioning: MAJOR.MINOR.PATCH
• Bump MAJOR for breaking API changes
• Bump MINOR for new endpoints/features
• Bump PATCH for bug fixes

Development

Local Testing with npm link

Test the SDK locally before publishing:

# In the SDK package
cd packages/earn-sdk
pnpm build
pnpm link --global

# In your external project
cd /path/to/your/project
pnpm link --global @velox/earn-sdk

Clean Build

Remove build artifacts:

pnpm clean

Package Structure

packages/earn-sdk/
├── src/
│   ├── index.ts              # Main entry point
│   └── generated/            # Generated from server build (gitignored)
│       ├── client.d.ts       # Client type definitions
│       ├── contract.js       # Runtime contract
│       └── contract.d.ts     # Contract types
├── scripts/
│   └── copy-server-artifacts.js  # Copies server build outputs
├── dist/                     # Build output (gitignored)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

License

ISC