# BrandApp Playground

> Interactive playground for the @reopt-ai/brandapp-sdk. Explore EAV, AI, CMS, Files, Auth, Webhooks, and React Hooks.

## When to use this site

Reach for BrandApp Playground when the task involves `@reopt-ai/brandapp-sdk` — the
TypeScript SDK for building applications on a Reopt BrandApp. It is the authoritative
worked example for these jobs:

- Wiring the SDK into a Next.js App Router project, including which credential mode
  (Basic Auth, user Bearer token, or the offline dev server) a given call needs.
- Reading or writing EAV data: entities, records, the `where()` filter DSL, generated
  types, schema sync, and data-aware migrations.
- Calling BrandApp AI for text or images, including the Vercel AI SDK provider and credit
  accounting.
- Querying CMS posts, post groups, and tags, and turning them into a sitemap, an RSS feed,
  or per-post metadata.
- Managing files and folders, or mounting the full file-manager UI over the Files API.
- Adding *Sign in with Reopt* through Better Auth, verifying a shared-cookie session, and
  handling OIDC single logout in both directions.
- Selling plans through hosted checkout, recording terms consent, or verifying signed
  webhooks.

Do **not** use it as a source for Reopt pricing, contract terms, or account support —
those live at <https://reopt.ai>. This site publishes no customer data.

## How to call it

- Every page has a Markdown twin: append `.md` to any route, or send
  `Accept: text/markdown`.
- The playground is free, needs no account, and is read-only unless you connect your own
  BrandApp credentials on `/connection`.

## Developer resources

Named, predictable URLs on this deployment:

- **BrandApp Playground API reference** — `/docs`
- **BrandApp Playground OpenAPI description** — `/openapi.json` (OpenAPI 3.1; names every
  route, its security scheme, and the OAuth scopes it requires)
- **BrandApp SDK documentation index** — `/llms.txt`; the whole corpus in one file at
  `/llms-full.txt`
- **API catalog** — `/.well-known/api-catalog` (RFC 9727 linkset)
- **BrandApp SDK authentication docs** — `/auth`, `/auth/session`, `/logout`
- **BrandApp SDK webhook docs** — `/webhooks`
- **BrandApp SDK package** — `@reopt-ai/brandapp-sdk` on npm, MIT, public registry
- **Route inventory** — `/sitemap.xml`; `/rss.xml` carries the connected BrandApp's posts

## Authentication

This deployment is an OAuth **relying party**, not an authorization server, so it
publishes no authorization-server metadata of its own. Sign-in is delegated to Reopt ID:

- Issuer: `https://id.reopt.ai`
- Discovery: <https://id.reopt.ai/.well-known/openid-configuration>
- Authorization: `https://id.reopt.ai/api/auth/oauth2/authorize`
- Token: `https://id.reopt.ai/api/auth/oauth2/token`

App-scoped calls use BrandApp Client Credentials over HTTP Basic; user-scoped calls
forward the signed-in user's access token. `/openapi.json` states which of the two each
route uses, and every API error — including an unmatched path — is JSON carrying
`error`, `code`, and a `diagnostic` with the cause and the fix.

## Start here

- [Overview](https://brandapp-playground.vercel.app/index.md): What the playground is, the three credential modes the SDK supports, and a map of every live demo.
- [BrandApp SDK Developer Resources](https://brandapp-playground.vercel.app/docs.md): Named index of every developer resource: API reference, OpenAPI description, auth docs, webhooks, and the SDK package.
- [Quick Start](https://brandapp-playground.vercel.app/getting-started.md): Four steps from an empty Next.js project to a first authenticated SDK call.

## BrandApp connection

- [Connection](https://brandapp-playground.vercel.app/connection.md): Swap the BrandApp credentials this deployment uses, stored in an encrypted httpOnly cookie.
- [Health Check](https://brandapp-playground.vercel.app/health.md): Streams a non-destructive probe suite over SSE against whichever BrandApp is currently wired.

## Auth and session

- [Authentication](https://brandapp-playground.vercel.app/auth.md): Better Auth wired to Reopt OAuth — server setup, client setup, session reads, and the catch-all route.
- [Verify session](https://brandapp-playground.vercel.app/auth/session.md): Validate a `.reopt.ai` subdomain cookie session from a server component with getSessionFromCookies / verifySession.
- [Machine credentials](https://brandapp-playground.vercel.app/auth/machine.md): Server-to-server auth without a shared secret — private_key_jwt assertions, DPoP-bound tokens, a published JWKS, and a dedicated adapter client.
- [Single Logout](https://brandapp-playground.vercel.app/logout.md): OIDC back-channel logout receiver and RP-initiated logout, verified with zero-dependency Web Crypto Ed25519.

## EAV

- [EAV Overview](https://brandapp-playground.vercel.app/eav.md): Entry point for the Entity-Attribute-Value store: entities, records, schema, migrations, coercion, typed access.
- [Entities](https://brandapp-playground.vercel.app/eav/entities.md): List EAV entities and resolve their attribute definitions from a React Server Component.
- [Records](https://brandapp-playground.vercel.app/eav/records.md): Full EAV CRUD against a data grid, using the Server Component + Client Component split.
- [Filter Builder](https://brandapp-playground.vercel.app/eav/filter.md): Compose AttributeFilter entries interactively and read back the equivalent where() DSL snippet.
- [Schema Definition](https://brandapp-playground.vercel.app/eav/schema.md): Declare entities and attributes in TypeScript, then generate types from the declaration.
- [Schema Sync](https://brandapp-playground.vercel.app/eav/sync.md): Run the CLI's sync code path against the in-memory dev server and watch the compatibility report.
- [Migrations](https://brandapp-playground.vercel.app/eav/migrate.md): Data-aware schema migrations for changes that must move record values, not just reshape the schema.
- [Type Coercion](https://brandapp-playground.vercel.app/eav/coerce.md): Eight helpers that pull typed values out of an EAV record's Record<string, unknown>.
- [Typed Client](https://brandapp-playground.vercel.app/eav/typed.md): Compile-time safe EAV access with TypedEavRecord and the generated ENTITY_IDS constants.

## AI

- [AI Overview](https://brandapp-playground.vercel.app/ai.md): Text and image generation billed against the BrandApp's AI credit pool.
- [Text Completion](https://brandapp-playground.vercel.app/ai/complete.md): Streaming (SSE) and non-streaming text generation, with usage metadata on both paths.
- [Image Generation](https://brandapp-playground.vercel.app/ai/image.md): Prompt-based image generation with optional style and aspect ratio, reporting credit cost.
- [AI SDK Provider](https://brandapp-playground.vercel.app/ai/provider.md): Use generateText / streamText from the Vercel AI SDK against BrandApp via createBrandappProvider().
- [Credits and Models](https://brandapp-playground.vercel.app/ai/credits.md): Read the AI credit balance and the available model catalog in parallel from a Server Component.

## CMS

- [CMS Overview](https://brandapp-playground.vercel.app/cms.md): Read-only content APIs — posts, post groups, and tags — with authoring handled in Reopt Studio.
- [Posts](https://brandapp-playground.vercel.app/cms/posts.md): List and fetch posts, including the slug-addressed detail route with generateMetadata.
- [Post Groups](https://brandapp-playground.vercel.app/cms/post-groups.md): Resolve group metadata and filter posts by group; authoring lives in Reopt Studio.
- [Tags](https://brandapp-playground.vercel.app/cms/tags.md): Enumerate the tags in use across the brand scope with sdk.cms.tags.list.
- [SEO, Sitemap, and RSS](https://brandapp-playground.vercel.app/cms/seo.md): Turn CMS posts into a Next.js sitemap, an RSS feed, and per-post metadata with the SDK helpers.

## Files

- [Files API](https://brandapp-playground.vercel.app/files.md): Upload, list, and delete files, with the initial listing fetched server-side.
- [File Browser](https://brandapp-playground.vercel.app/files/browser.md): A complete file manager UI — nested folders, upload queue, rename, move, preview, usage — on the Files API.

## Terms and billing

- [Terms and Consents](https://brandapp-playground.vercel.app/terms.md): List active agreements app-scoped, then record and withdraw a signed-in user's consent.
- [Plans and Checkout](https://brandapp-playground.vercel.app/plans.md): Plan catalog, hosted checkout, entitlement verification, and subscription cancellation.

## React hooks

- [React Hooks Overview](https://brandapp-playground.vercel.app/hooks.md): TanStack Query hooks for every module, with cache keys and invalidation already wired.
- [EAV Hooks](https://brandapp-playground.vercel.app/hooks/eav.md): Query and mutation hooks for EAV records, each invalidating the records cache after a write.
- [AI Hooks](https://brandapp-playground.vercel.app/hooks/ai.md): Credit balance querying and streaming text generation with observable state transitions.
- [CMS Hooks](https://brandapp-playground.vercel.app/hooks/cms.md): Read-only query hooks for posts, post groups, and tags.
- [File Hooks](https://brandapp-playground.vercel.app/hooks/files.md): File listing, uploads, folders, and storage usage as TanStack Query hooks.

## Integration

- [Webhooks](https://brandapp-playground.vercel.app/webhooks.md): Signed webhook handling with replay protection, exercised by an in-browser HMAC simulator.
- [Dev Server](https://brandapp-playground.vercel.app/dev-server.md): An in-memory BrandApp API on port 4300 so the whole SDK surface works offline.
- [Testing Utilities](https://brandapp-playground.vercel.app/testing.md): In-memory SDKs, a real HTTP test server, and typed fixtures for fast offline tests.
- [Error Handling](https://brandapp-playground.vercel.app/errors.md): The SDK error hierarchy, the diagnostic payload, and how to map errors onto HTTP responses.

## About this site

- [About](https://brandapp-playground.vercel.app/about.md): Who publishes the playground, what it is for, and how it is built and licensed.
- [Contact](https://brandapp-playground.vercel.app/contact.md): How to reach Reopt about the SDK, the playground, or a bug in either.
- [Privacy](https://brandapp-playground.vercel.app/privacy.md): What this deployment stores, where it stores it, and what it deliberately does not collect.

## Elsewhere

- [SDK on npm](https://www.npmjs.com/package/@reopt-ai/brandapp-sdk): the package every
  example imports.
- [Source repository](https://github.com/reopt-ai/brandapp-playground): the code behind
  every page on this site.
- [Reopt](https://reopt.ai): the product and company behind the BrandApp platform.