Open source

TypeScript SDK

GitHubDeepwiki
The easy way to build on your favorite framework

Focus on building unique customer experiences while the SDK handles complex commerce logic like inventory, orders, payments, and user management. No bloat, it's modular and easy to extend.

Why use the Geins SDK?

Developer-friendly experience

The SDK is built with developers in mind. Full TypeScript support means you get intelligent autocomplete, type safety, and comprehensive documentation right in your IDE. No more guessing API response shapes or hunting through documentation—the types guide you every step of the way.

Modular architecture

Instead of one monolithic package, the SDK is organized into focused modules. Install only what you need, keeping your bundle size lean and your dependencies clear:

  • @geins/core - Foundation for API interactions, GraphQL client, configuration, and event management
  • @geins/cms - Content management for pages, menus, and content areas
  • @geins/crm - Customer relationship management with authentication, profile management, and order history
  • @geins/oms - Order management system with cart, checkout, and order services
  • @geins/pim - Product information management and search

Open source and community-driven

The SDK is open source under the MIT License, meaning you can contribute improvements, customize for your needs, and benefit from community-driven enhancements. We believe in transparency and collaborative development.

Production-ready

Built on Node.js and fully compatible with modern JavaScript and TypeScript environments, the SDK is battle-tested and ready for production workloads. Whether you're building server-side applications or integrating with frameworks like Next.js, Nuxt, or SvelteKit, the SDK fits seamlessly into your stack.

Getting started

Installation

Install the core package and any modules you need:

pnpm add @geins/core @geins/cms @geins/crm @geins/oms @geins/pim

Basic setup

Initialize the SDK with your configuration:

app.ts
import { GeinsCore } from '@geins/core';
import { GeinsCMS } from '@geins/cms';
import { GeinsCRM } from '@geins/crm';
import { GeinsOMS } from '@geins/oms';

const geinsCore = new GeinsCore({
  apiKey: '{MERCHANT_API_KEY}',
  accountName: '{ACCOUNT_NAME}',
  channel: '{CHANNEL_ID}',
  locale: '{LANGUAGE_ID}',
  market: '{MARKET_ID}',
});

const geinsCMS = new GeinsCMS(geinsCore);
const geinsCRM = new GeinsCRM(geinsCore);
const geinsOMS = new GeinsOMS(geinsCore);

With just a few lines of code, you're ready to interact with the Geins API using fully typed methods.

What can you build?

The SDK empowers you to build:

  • Headless storefronts - Create custom shopping experiences with complete control over design and UX
  • Content management systems - Build CMS-powered sites with dynamic pages and widgets
  • Customer portals - Develop account management interfaces with authentication and profile features
  • Product catalogs - Implement sophisticated product browsing and search experiences
  • Multi-market applications - Support multiple channels, markets, and languages with built-in multi-market support

Core packages

@geins/core

The foundation package provides a unified GraphQL client for querying any commerce data, multi-channel support, event system for tracking commerce events, cookie management for sessions, and JWT token handling for secure authentication. It provides the base functionality that other packages build upon.

@geins/cms

Manage dynamic content with dedicated services for menus, content pages, and content areas. Build CMS-powered sites with navigation, marketing pages, and dynamic content blocks—all with type-safe methods.

@geins/crm

Handle customer authentication with login, logout, registration, and token refresh. Manage user profiles with create, update, and delete operations. Includes password management with change and reset functionality, plus access to customer order history.

@geins/oms

Complete order management system with cart service for adding, updating, and removing items, checkout service for handling the entire checkout flow with token-based security, and order service for creating and retrieving orders. Build complete shopping experiences without managing complex order logic.

@geins/pim

Work with product data efficiently. List products, fetch details, handle search functionality, and manage complex product information—all with type-safe methods designed for sophisticated product browsing experiences.

Repository structure

The Geins SDK is organized as a monorepo, keeping all packages and documentation in a single repository for easier maintenance and development:

repository structure
geins-sdk/
├── packages/          # Core SDK packages (@geins/core, @geins/cms, etc.)
├── apps/              # Applications (docs, examples)
│   └── docs/          # SDK documentation site
├── schemas/           # Shared data schemas and type definitions
├── scripts/           # Build, test, and deployment utilities
├── test/              # Test suites and test utilities
├── .github/           # GitHub Actions workflows for CI/CD
│   └── workflows/
├── .husky/            # Git hooks for code quality checks
└── .changeset/        # Changeset configuration for versioning

This structure promotes:

  • Code sharing - Shared types and utilities live in schemas/ and are reused across packages
  • Consistency - Unified build, test, and release processes for all packages
  • Developer experience - Single repository makes it easier to contribute and understand the codebase
  • Documentation - Documentation lives alongside the code, keeping it always in sync

Technology stack

The SDK is built with modern, developer-friendly technologies:

Core technologies

  • TypeScript - Full TypeScript implementation provides type safety, IntelliSense, and excellent developer experience
  • Node.js - Runtime environment ensuring compatibility with server-side JavaScript applications
  • ES Modules - Modern JavaScript module system for tree-shaking and optimal bundle sizes

Development tools

  • Turborepo - High-performance build system for fast incremental builds and intelligent caching
  • Changesets - Semantic versioning and automated changelog generation
  • Husky - Git hooks for enforcing code quality standards before commits
  • GitHub Actions - Continuous integration and deployment pipelines for automated testing and releases

Build and testing

  • Modern build tooling - Optimized build processes for each package
  • Comprehensive test suite - Test coverage across all packages ensures reliability

Package management

The SDK uses Turborepo to power the monorepo, providing fast incremental builds, intelligent caching, and parallel task execution. Built on top of npm workspaces, Turborepo ensures consistent dependency versions while dramatically improving build performance through smart caching and task orchestration.

Repository resources

Official links

Contributing

The SDK is open source under the MIT License, and we welcome contributions! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your contributions help make the SDK better for everyone.

To get started:

  1. Report issues - Found a bug or have a feature request? Open an issue on GitHub
  2. Submit pull requests - Check the contributing guidelines in the repository's README
  3. Improve documentation - Help us make the SDK easier to understand and use
  4. Share feedback - Let us know what features would make your development experience better

Examples and starter templates

See the SDK in action with these example projects and starter templates:

Geins Studio

The comprehensive admin interface for your commerce platform

Geins Checkout

Open-source checkout solution for Geins e-commerce backend. Use it to manage transactions with or without a storefront.