# trama-types

> Canonical TypeScript types for the Trama ecosystem — `TramaProduct`, `TramaCart`, `TramaCollection`, and the rest of the public schema.

[![npm](https://img.shields.io/npm/v/trama-types.svg)](https://www.npmjs.com/package/trama-types)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

## What this is

Pure TypeScript type declarations. No runtime, no dependencies. Just the schema every other Trama package agrees on.

Use it whenever you need to:
- Build a custom platform connector (output `TramaProduct[]`, etc.)
- Pass commerce data between services
- Type your own commerce frontend without coupling to a specific backend

## Install

```bash
npm install trama-types
```

## Quick example

```ts
import type { TramaProduct, TramaCart, FetchProductsOptions } from 'trama-types';

function PriceTag({ product }: { product: TramaProduct }) {
  // product.price.amount is always in smallest currency unit (cents)
  // product.price.currency is always ISO 4217
  return <span>{product.price.formatted}</span>;
}
```

## Schema highlights

- **Money is in cents.** `TramaPrice.amount` is the smallest currency unit (e.g. `2999` = $29.99). No floats.
- **Dates are ISO 8601 strings.** Pass them to `new Date()` if you need objects.
- **Internal IDs are UUIDs.** `id` is a fresh UUID; `platformId` preserves the original ID from Wix/Shopify/Webflow.
- **`metadata` is the escape hatch.** Each `TramaProduct` carries the raw upstream payload in `metadata` so power users never lose information.
- **`TramaMember` is a verified identity.** Returned by `POST /members/verify` after Trama checks the platform session token live — never constructed client-side.
- **`TramaCmsCollection` covers content sites.** A discoverable content collection: Webflow CMS collection, Wix Data collection, or Shopify metaobject type.

## Used by

- [`trama-sdk`](https://www.npmjs.com/package/trama-sdk) — React hooks
- [`trama-connectors`](https://www.npmjs.com/package/trama-connectors) — platform connector library
- The hosted [Trama](https://gotrama.com) Bridge API

## Stability

This package follows [SemVer](https://semver.org/). Breaking changes only happen in major versions, and we treat changes here as cross-cutting since multiple packages consume them.

## License

MIT — see [LICENSE](./LICENSE).