npm.io
1.0.33 • Published 18h agoCLI

priceos

Licence
—
Version
1.0.33
Deps
5
Size
1.6 MB
Vulns
0
Weekly
0
SummaryDependencyVersions

PriceOS SDK (priceos)

Use PriceOS in your backend and React app to evaluate feature access and track usage.

Install

npm i priceos

Set your API key in your backend environment:

PRICEOS_API_KEY=pos_ab234cdef...

PRICEOS_API_KEY must never be exposed client-side.

Quickstart (Node.js)

Create features in PriceOS first:

Generate typed feature keys (recommended):

npx priceos generate-types --out ./src/priceos.types.d.ts

Use the SDK:

import { PriceOS } from "priceos";
import type { MyFeatures } from "./priceos.types";

const priceos = new PriceOS<MyFeatures>(process.env.PRICEOS_API_KEY!);

const premiumSupport = await priceos.features.getAccess("customer_123", "premium_support");

if (premiumSupport.hasAccess) {
  // allow action
}

await priceos.usage.track({
  customerId: "customer_123",
  featureKey: "team_seats",
  amount: 1,
});

Next.js backend handlers (priceos/next)

Use built-in handlers for:

  • GET /api/priceos/v1/customer
  • GET /api/priceos/v1/feature-access
  • GET /api/priceos/v1/products
  • POST /api/priceos/v1/usage
  • GET /api/priceos/v1/usage-events
  • GET /api/priceos/v1/pricing-table
  • POST /api/priceos/v1/checkout
  • POST /api/priceos/v1/customer-portal

App Router:

// app/api/priceos/[...path]/route.ts
import { priceosHandler } from "priceos/next";

export const { GET, POST } = priceosHandler({
  identifyCustomer: async (request: Request) => {
    // resolve your current user/customer identity
    return { customerId: "customer_123" };
  },
});

Pages Router:

// pages/api/priceos/[...path].ts
import { priceosPagesHandler, type PriceOSPagesRequest } from "priceos/next";

export default priceosPagesHandler({
  identifyCustomer: async (_req: PriceOSPagesRequest) => {
    return { customerId: "customer_123" };
  },
});

React hooks (priceos/react)

Wrap your app:

import { PriceOSProvider } from "priceos/react";

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <PriceOSProvider>{children}</PriceOSProvider>;
}

Read feature access:

import { useFeatureAccess } from "priceos/react";
import type { MyFeatures } from "./priceos.types";

const { featureAccess, isLoading, error } = useFeatureAccess<MyFeatures>();

Track usage:

import { useTrackUsage } from "priceos/react";
import type { MyFeatures } from "./priceos.types";

const { trackUsage } = useTrackUsage<MyFeatures>();
await trackUsage({ featureKey: "team_seats", amount: 1 });

List usage events:

import { useUsageEvents } from "priceos/react";
import type { MyFeatures } from "./priceos.types";

const { usageEvents, isLoading, hasMore, getMore } = useUsageEvents<MyFeatures>("team_seats");

List products:

import { useProducts } from "priceos/react";

const { products, isLoading, error } = useProducts();

Build your own pricing UI:

import { useCheckout, usePricingTable } from "priceos/react";

const { pricingTable } = usePricingTable({ pricingTableKey: "marketing-pricing" });
const { openCheckout } = useCheckout();

await openCheckout({
  productKey: pricingTable!.plans[0].productKey,
  stripePriceId: pricingTable!.plans[0].monthlyPrice?.stripePriceId,
  pricingTableReleaseId: pricingTable!.table?.releaseId,
});

Start checkout:

import { useCheckout } from "priceos/react";

const { openCheckout } = useCheckout();
await openCheckout({
  productKey: "starter_monthly",
  successUrl: "https://app.acme.com/settings/billing?checkout=success",
  cancelUrl: "https://app.acme.com/settings/billing?checkout=canceled",
});

Open customer portal:

import { useCustomerPortal } from "priceos/react";

const { openCustomerPortal } = useCustomerPortal();
await openCustomerPortal();

API surface

PriceOS client groups:

  • customers: get, link, create, update, delete
  • features: getAccess(customerId, featureKey?)
  • products: list(), get(productKey)
  • pricingTables: list, create, getRelease, updateDraft, createRelease, publish, deleteDraft
  • usage: track, set, getEvent, updateEvent, deleteEvent, deleteEvents, trackBatch, listEvents
  • bonuses: create, list, update, delete

Error handling:

  • Throws PriceOSError with message, optional status, and optional details.

CLI

Generate local feature types:

npx priceos generate-types

Options:

  • --api-key <key>: use explicit API key (otherwise checks .env.local, .env, then process.env)
  • --out <path>: output file path (default priceos.d.ts)
  • --out-dir <path>: output directory (ignored when --out is set)
  • -h, --help: CLI help

Docs