# SMScene API — llms.txt
# Full machine-readable reference for the SMScene REST API.
# Base URL: https://smscene.com/api/v1

## Authentication
All requests need:  Authorization: Bearer <key>
Keys are generated at https://smscene.com/profile?tab=integrations

## Credits & Pricing
1 credit = $1.00. Each successful request costs 0.05 credits ($0.05).
Failed requests (4xx/5xx) are never charged.
Low balance returns HTTP 402 with { balance, required } in error.details.

## Error shape
{ "success": false, "error": { "code": "...", "message": "...", "details": {...} }, "meta": { "timestamp": "..." } }
Codes: UNAUTHORIZED(401) INSUFFICIENT_CREDITS(402) FORBIDDEN(403) NOT_FOUND(404) BAD_REQUEST(400) INTERNAL_ERROR(500)

## Endpoints

### GET /projects
List all projects for the authenticated user, newest first.
Response 200: { success, data: { projects: [...] } }

### GET /projects/:id
Fetch one project with participants and messages.
Response 200: { success, data: { project, participants, messages } }

### POST /projects
Create a project. All body fields optional. Returns 201.
Body fields:
  name             string   default "Untitled Project"
  phoneModel       string   default "ios18"
  theme            string   "light"|"dark"  default "dark"
  backgroundColor  string   hex or image URL  default "#050505"
  os               string   "ios"|"android"
  clock            string   fixed status-bar time e.g. "9:41"
  battery          number   0-100
  signal           number   0-4
  autoReadReceipts boolean  default false
  isFrameless      boolean  default false
  showKeyboard     boolean  default false
  participants     array    see Participants
  messages         array    see Messages
Response 201: { success, data: { project, participants, messages } }

### PATCH /projects/:id
Update any subset of fields. Passing participants or messages replaces those arrays entirely.
Same body fields as POST. Response 200.

### DELETE /projects/:id
Permanently delete a project.
Response 200: { success, data: { deleted: true } }

## Participants
Each participant object:
  id         string   optional - friendly key e.g. "me", "bob". Auto-UUID if omitted.
  name       string   REQUIRED - display name
  alignment  string   REQUIRED - "right" (sender/you) | "left" (recipient/them)
  color      string   bubble hex colour, default #3b82f6
  avatar     string   profile picture URL

Reserved id "system" is used for notifications, reactions, read receipts, title cards.
Participant ids must be unique within a request.

## Messages
Common fields:
  participantId  string   REQUIRED - participant id or "system"
  type           string   REQUIRED - see types below
  content        string   text to display
  delay          number   REQUIRED - total window in ms (must satisfy timing constraint)
  typingSpeed    number   characters per second, default 8
  padStart       number   silence before typing begins (ms)
  padEnd         number   hold time after bubble appears (ms)

Participant message types (use with a real participant id):
  text    - standard bubble with typing animation
  image   - media bubble; include mediaUrl field
  type    - animated "..." typing indicator only
  typo    - bubble that types a mistake then corrects it

System message types (use with participantId "system"):
  notification  - centred label e.g. "Today 9:41 AM"
  react         - emoji reaction; requires reactToId (message id to react to)
  read          - "Read" / "Delivered" receipt
  title_card    - full-screen or banner overlay

Typo fields (type "typo"):
  typos          array    [{ id, typo, correction, backspaceDelay? }]
  backspaceDelay number   default ms before backspacing, default 1000

Title card fields (type "title_card", participantId "system"):
  tcDuration       number   ms the card stays visible
  tcSize           string   "fullscreen"|"banner"|"custom"
  tcLayer          string   "canvas"|"screen"
  tcBgColor        string   background hex
  tcBgImage        string   background image URL
  tcBgOpacity      number   0-1
  tcTextColor      string   text hex
  tcFontSize       number   px
  tcFontWeight     string   "normal"|"bold"
  tcFontStyle      string   "normal"|"italic"
  tcEnterAnimation string   "none"|"fade"|"slide-up"|"slide-down"|"zoom"
  tcWidth          number   % of canvas width (custom only)
  tcHeight         number   % of canvas height (custom only)
  tcX              number   horizontal offset (custom only)
  tcY              number   vertical offset (custom only)

## Timing constraint
For text, image, typo messages the delay must satisfy:
  padStart + typingTime + typoOverhead + padEnd < delay

  typingTime = content.length / typingSpeed * 1000  (ms)
  typoOverhead (per typo) = (typo.length * 2 / typingSpeed * 1000) + backspaceDelay

The x2 accounts for typing wrong chars then backspacing them.
Default typingSpeed = 8 cps (~125ms/char).
The API returns a 400 with the exact minimum delay required if this fails.

## Minimal full example
POST /projects body:
{
  "name": "My Scene",
  "participants": [
    { "id": "me",   "name": "Alice", "alignment": "right" },
    { "id": "them", "name": "Bob",   "alignment": "left"  }
  ],
  "messages": [
    { "participantId": "them", "type": "text", "content": "Hey!", "delay": 3000 },
    { "participantId": "me",   "type": "text", "content": "Hey back!", "delay": 4200 }
  ]
}