@uppercase-m/colonyone-sdk

Framework-agnostic TypeScript SDK for the ColonyOne Platform. Access commerce, content, authentication, and loyalty features from any frontend.

Installation

pnpm add @uppercase-m/colonyone-sdk

Or with npm:

npm install @uppercase-m/colonyone-sdk

Or with yarn:

yarn add @uppercase-m/colonyone-sdk

Quick Start

import { ColonyOne } from '@uppercase-m/colonyone-sdk'

const client = new ColonyOne({
  baseUrl: 'https://your-colonyone-instance.com',
  apiKey: 'pk_live_...',
})

// List products
const { data: products } = await client.commerce.products.list()
console.log(products)

Namespaces

Commerce

Access products, cart, checkout, orders, customers, and banners.

client.commerce.products.list()
client.commerce.products.get(id)
client.commerce.cart.create({ region_id })
client.commerce.cart.get(cartId)
client.commerce.cart.addItem(cartId, { variant_id, quantity })
client.commerce.checkout.createPaymentSessions(cartId)
client.commerce.checkout.complete(cartId)
client.commerce.orders.list()
client.commerce.customers.get()
client.commerce.banners.list()

Content

Manage pages, posts, media, categories, and global settings.

client.content.pages.getBySlug(slug)
client.content.posts.list()
client.content.media.get(id)
client.content.categories.list()
client.content.globals.get(slug)

Auth

Handle login, registration, logout, session management, and password reset.

client.auth.login({ email, password })
client.auth.register({ email, password, first_name, last_name })
client.auth.logout()
client.auth.session()
client.auth.forgotPassword({ email })
client.auth.resetPassword({ email, token, password })

Loyalty

Earn and redeem points, manage tiers, access rewards, and track referrals.

client.loyalty.points.balance()
client.loyalty.points.history()
client.loyalty.tiers.current()
client.loyalty.rewards.list()
client.loyalty.rewards.redeem({ reward_id })
client.loyalty.referrals.getLink()
client.loyalty.referrals.status()

Authentication

Login Flow

const { customer, accessToken } = await client.auth.login({
  email: '[email protected]',
  password: 'password',
})

// Token is automatically stored and included in subsequent requests
console.log(customer.email)
console.log(accessToken)

Session Management

// Get current customer profile (requires prior login or setAccessToken)
const customer = await client.auth.session()

// Listen for auth state changes via the onAuthStateChange config callback
const client = new ColonyOne({
  baseUrl: 'https://your-colonyone-instance.com',
  apiKey: 'pk_live_...',
  onAuthStateChange: (state) => {
    if (state.authenticated) {
      console.log('Logged in')
    } else {
      console.log('Logged out')
    }
  },
})

Error Handling

All errors thrown by the SDK are instances of ColonyOneError:

import { ColonyOneError } from '@uppercase-m/colonyone-sdk'

try {
  await client.commerce.products.get('invalid-id')
} catch (error) {
  if (error instanceof ColonyOneError) {
    console.log(error.code) // Machine-readable code
    console.log(error.statusCode) // HTTP status code
    console.log(error.message) // Human-readable message
    console.log(error.details) // Additional context
  }
}

Tree-Shaking

Import from sub-paths to enable tree-shaking:

import { CommerceClient } from '@uppercase-m/colonyone-sdk/commerce'
import { ContentClient } from '@uppercase-m/colonyone-sdk/content'
import { AuthClient } from '@uppercase-m/colonyone-sdk/auth'
import { LoyaltyClient } from '@uppercase-m/colonyone-sdk/loyalty'

Next.js App Router

Use React cache() for per-request SDK instances:

import { cache } from 'react'
import { ColonyOne } from '@uppercase-m/colonyone-sdk'

const getSDK = cache(() => {
  return new ColonyOne({
    baseUrl: process.env.NEXT_PUBLIC_COLONYONE_URL!,
    apiKey: process.env.COLONYONE_API_KEY!,
  })
})

export default async function Page() {
  const sdk = getSDK()
  const { data: products } = await sdk.commerce.products.list()

  return <div>{/* Render products */}</div>
}

Debug Mode

Enable debug logging to troubleshoot API calls:

const client = new ColonyOne({
  baseUrl: 'https://your-colonyone-instance.com',
  apiKey: 'pk_live_...',
  debug: true,
})

Health Check

Verify SDK connectivity:

// Basic health check
const health = await client.health()

// Deep health check (includes all service dependencies)
const deepHealth = await client.health({ deep: true })

API Reference

See TypeScript declarations for the full API reference. All types and method signatures are available in the package's type definitions.

Requirements

• Node.js 18+
• TypeScript 5.0+

License

UNLICENSED (Private/Proprietary)