Codex SDK

This package exists to help you develop on top of the Codex API (https://docs.codex.io).

It provides generated TypeScript types and convenient methods to access the GraphQL API with full type safety.

Note

We've changed our name from Defined to Codex.

You will see references to our previous company name, Defined, while we make the switch to Codex.

Features

• 🚀 Fully Typed: Generated TypeScript types for all GraphQL operations
• 📦 Tree Shakeable: ESM support with optimized bundle size
• 🔄 Real-time: WebSocket subscriptions support
• 🛠 Developer Friendly: Comprehensive examples and documentation

Installation

Package Manager	Command
npm	npm install @codex-data/sdk
yarn	yarn add @codex-data/sdk
pnpm	pnpm add @codex-data/sdk

Usage

Follow one of the examples in the examples directory, or simply run.

Fetch a token.

import { Codex } from "@codex-data/sdk";

const sdk = new Codex(MY_API_KEY);

sdk.queries
  .token({
    input: {
      address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
      networkId: 56,
    },
  })
  .then(console.log);

Use your own GraphQL selections

import { Codex } from "@codex-data/sdk";

const sdk = new Codex(process.env.CODEX_API_KEY || "");

// Using the raw GraphQL client
sdk
  .send<{ getNetworks: Array<{ id: string; name: string }> }>(
    `
  query GetNetworks {
    getNetworks { id name }
  }
`,
    {},
  )
  .then((res) => {
    console.log("Networks: ", res.getNetworks);
  });

Subscribe to real-time data

import { Codex } from "@codex-data/sdk";

const sdk = new Codex(process.env.CODEX_API_KEY || "");

// Subscribe to price updates
sdk.subscriptions.onPriceUpdated(
  {
    address: "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
    networkId: 56,
  },
  (result) => {
    if (result.data) {
      console.log("Price updated:", result.data.onPriceUpdated);
    }
  },
);

Development

Prerequisites

• Node.js >= 17.5.0
• pnpm (recommended) or npm/yarn
• curl for fetching the GraphQL schema

Building from Source

# Install dependencies
pnpm install

# Build the SDK
pnpm run build

Running Examples

All examples require a Codex API key. Get your API key at docs.codex.io.

Simple Example

Basic usage with inline GraphQL queries:

cd examples/simple
pnpm install
CODEX_API_KEY=your_api_key pnpm run dev

Codegen Example

Shows how to use GraphQL Code Generator for fully typed queries:

cd examples/codegen
pnpm install
pnpm run codegen
CODEX_API_KEY=your_api_key pnpm run dev

Next.js Example

Full-stack example with a Next.js application:

cd examples/next
pnpm install
NEXT_PUBLIC_CODEX_API_KEY=your_api_key pnpm run dev

Package Structure

The SDK is built with modern tooling and provides both CommonJS and ESM builds:

@codex-data/sdk/
├── dist/
│   ├── index.js      # CommonJS entry point
│   ├── index.mjs     # ESM entry point
│   ├── index.d.ts    # TypeScript definitions
│   └── sdk/          # SDK implementation
├── README.md
└── package.json

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Development Scripts

• pnpm run build - Build the SDK for production
• pnpm run test - Run the test suite
• pnpm run lint - Lint the codebase
• pnpm run clean - Clean build artifacts

Releasing

Publishing Beta Versions

For testing releases before making them public:

1. Update the version in package.json to a beta version:

   "version": "2.0.0-beta.0"

2. Publish to the beta tag:

   pnpm run publish:beta

3. Test the beta version:

   npm install @codex-data/sdk@beta

Users installing without the @beta tag will continue to receive the latest stable version.

Publishing Production Releases

1. Update the version in package.json to a production version:

   "version": "2.0.0"

2. Publish to the latest tag:

   pnpm run publish:latest

Note: The prepublishOnly script automatically runs the full build before publishing, ensuring the package is always built before release.