Configuration

Configure the Owostack SDK with your API keys and environment settings.

Initialization

import { Owostack } from "@owostack/core";

const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY,
  mode: "live", // or "sandbox"
});

Configuration Options

Option	Type	Required	Description
`secretKey`	`string`	✅	Your API secret key
`mode`	`"sandbox" \| "live"`	-	Environment mode (default: live)
`apiUrl`	`string`	-	Custom API URL (overrides mode)
`debug`	`boolean`	-	Enable debug logging
`catalog`	`CatalogEntry[]`	-	Declarative plan/feature definitions

Environment Modes

Use the mode option to switch between sandbox and live environments:

// Sandbox mode (uses test API keys and data)
const sandboxClient = new Owostack({
  secretKey: process.env.OWOSTACK_SANDBOX_SECRET_KEY,
  mode: "sandbox",
});

// Live mode (uses production API keys)
const liveClient = new Owostack({
  secretKey: process.env.OWOSTACK_LIVE_SECRET_KEY,
  mode: "live",
});

Mode-Based API URLs

sandbox: https://sandbox.owostack.com
live: https://api.owostack.com

Custom API URL

For self-hosted deployments or custom endpoints, use apiUrl. This takes precedence over mode:

const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY,
  apiUrl: "https://billing.mycompany.com",
  // mode is ignored when apiUrl is provided
});

URL Resolution Priority

The SDK resolves the API URL in this order:

Explicit apiUrl (highest priority)
Mode-based URL (sandbox/live)
Default URL (https://api.owostack.com)

Debug Mode

Enable debug mode for verbose logging:

const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY,
  mode: "sandbox",
  debug: true,
});

With Catalog

Pass a declarative catalog for plan/feature management:

import { metered, boolean, plan } from "@owostack/core";

const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY,
  mode: "live",
  catalog: [
    plan("pro", {
      name: "Pro",
      price: 2900,
      currency: "USD",
      interval: "monthly",
      features: [
        metered("api-calls").limit(10000),
        boolean("premium-support").enabled(),
      ],
    }),
  ],
});

// Sync catalog to server
await owo.sync();

Runtime Configuration

Override configuration at runtime (useful for CLI tooling):

const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY,
});

// Switch to sandbox mode
owo.setSecretKey(process.env.OWOSTACK_SANDBOX_SECRET_KEY);
owo.setApiUrl("https://sandbox.owostack.com");

Best Practices

Use environment variables - Never hardcode API keys
Separate sandbox/live keys - Use different keys for each environment
Use mode explicitly - Always specify mode in multi-environment setups
Custom URL overrides mode - When using apiUrl, mode is ignored

Examples

Development Setup

// config.ts
export const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SANDBOX_SECRET_KEY!,
  mode: "sandbox",
  debug: process.env.NODE_ENV === "development",
});

Production Setup

// config.ts
export const owo = new Owostack({
  secretKey: process.env.OWOSTACK_LIVE_SECRET_KEY!,
  mode: "live",
});

Dynamic Mode

// config.ts
const mode = process.env.OWOSTACK_MODE as "sandbox" | "live" | undefined;
const secretKey =
  mode === "sandbox"
    ? process.env.OWOSTACK_SANDBOX_SECRET_KEY
    : process.env.OWOSTACK_LIVE_SECRET_KEY;

export const owo = new Owostack({
  secretKey: secretKey!,
  mode: mode || "live",
});

Catalog Sync - Define plans and features declaratively
Quickstart - Get started with Owostack

Configuration

On this page