Spectrum TS

https://photon.codes/docs
Admin
Spectrum TS is a platform that allows developers to build AI agents once and deploy them across...
Tokens:162,856
Snippets:1,505
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install dependencies and run server

Source: https://photon.codes/docs/webhooks/quickstart

Commands to install Hono and start the development server.

```sh
bun add hono
bun --hot server.ts
```

--------------------------------

### Quick Start iMessage SDK

Source: https://photon.codes/docs/opensource/imessage-kit

Basic usage example for initializing the SDK and sending an iMessage.

```ts
import { IMessageSDK } from "@photon-ai/imessage-kit";

const sdk = new IMessageSDK();

await sdk.send("+1234567890", "Hello from iMessage Kit!");

await sdk.close();
```

--------------------------------

### Install iMessage Kit

Source: https://photon.codes/docs/opensource/imessage-kit

Installation commands for Bun and Node.js environments.

```bash
bun add @photon-ai/imessage-kit
```

```bash
npm install @photon-ai/imessage-kit better-sqlite3
```

--------------------------------

### Install spectrum-ts

Source: https://photon.codes/docs/spectrum-ts/getting-started

Standard installation commands for the full spectrum-ts package.

```bash
npm install spectrum-ts
```

```bash
pnpm add spectrum-ts
```

```bash
yarn add spectrum-ts
```

```bash
bun add spectrum-ts
```

--------------------------------

### Install Chat SDK and iMessage Adapter

Source: https://photon.codes/docs/integrations/chat-sdk

Install the required packages using pnpm.

```bash
pnpm add chat chat-adapter-imessage
```

--------------------------------

### Install the iMessage SDK

Source: https://photon.codes/docs/advanced-kits/imessage/getting-started

Install the package using your preferred package manager.

```bash
npm install @photon-ai/advanced-imessage
```

```bash
pnpm add @photon-ai/advanced-imessage
```

```bash
yarn add @photon-ai/advanced-imessage
```

```bash
bun add @photon-ai/advanced-imessage
```

--------------------------------

### Verify installation

Source: https://photon.codes/docs/cli/installation

Check the installed version and verify API connectivity.

```sh
photon --version
photon ping
```

--------------------------------

### Install lean dependencies

Source: https://photon.codes/docs/spectrum-ts/getting-started

Install only the core package and specific providers for a smaller footprint.

```bash
bun add @spectrum-ts/core @spectrum-ts/imessage @spectrum-ts/telegram
```

--------------------------------

### Install Photon CLI globally

Source: https://photon.codes/docs/cli/installation

Install the CLI globally to make the photon command available on your system PATH.

```sh
npm install -g @photon-ai/cli
```

```sh
pnpm add -g @photon-ai/cli
```

```sh
yarn global add @photon-ai/cli
```

```sh
bun add -g @photon-ai/cli
```

--------------------------------

### Install Scoped Packages

Source: https://photon.codes/docs/spectrum-ts/providers/imessage

Install only the core and iMessage packages for a lean installation.

```bash
bun add @spectrum-ts/core @spectrum-ts/imessage
```

--------------------------------

### Install WhatsApp Business SDK

Source: https://photon.codes/docs/advanced-kits/whatsapp/getting-started

Install the package using your preferred Node.js package manager. Requires Node.js 18+ or Bun.

```bash
npm install @photon-ai/whatsapp-business
```

```bash
pnpm add @photon-ai/whatsapp-business
```

```bash
yarn add @photon-ai/whatsapp-business
```

```bash
bun add @photon-ai/whatsapp-business
```

--------------------------------

### Create Gateway Route

Source: https://photon.codes/docs/integrations/chat-sdk

Implement a GET route to start the gateway listener for real-time message streaming in serverless environments.

```typescript
// app/api/imessage/gateway/route.ts
import { after } from "next/server";
import { bot } from "@/lib/bot";

export const maxDuration = 800;

export async function GET(request: Request): Promise<Response> {
  const cronSecret = process.env.CRON_SECRET;
  if (!cronSecret) {
    return new Response("CRON_SECRET not configured", { status: 500 });
  }

  const authHeader = request.headers.get("authorization");
  if (authHeader !== `Bearer ${cronSecret}`) {
    return new Response("Unauthorized", { status: 401 });
  }

  const durationMs = 600 * 1000;

  return bot.adapters.imessage.startGatewayListener(
    { waitUntil: (task) => after(() => task) },
    durationMs
  );
}
```

--------------------------------

### Login to Photon

Source: https://photon.codes/docs/cli/installation

Authenticate the CLI after global installation.

```sh
photon login
```

--------------------------------

### Install heif2jpeg using bun

Source: https://photon.codes/docs/utilities/heif2jpeg

Install the heif2jpeg package using bun. bun is a fast all-in-one JavaScript runtime.

```bash
bun add heif2jpeg
```

--------------------------------

### SIP URI Examples

Source: https://photon.codes/docs/spectrum-ts/providers/voice/inbound-calls

Examples of SIP URIs for encrypted TLS (sips:) and unencrypted TCP (sip:) signaling.

```text
sips:agent@voice.example.com:5061
sip:agent@voice.example.com:5060
```

--------------------------------

### Download standalone binary

Source: https://photon.codes/docs/cli/installation

Install the CLI as a standalone binary for environments without Node.js runtime dependencies.

```sh
# <os>: darwin | linux
# <arch>: arm64 | x64
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/latest/download/photon-<os>-<arch>
chmod +x /usr/local/bin/photon
photon --version
```

```sh
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/latest/download/photon-darwin-arm64
chmod +x /usr/local/bin/photon
```

--------------------------------

### Using the pho Alias

Source: https://photon.codes/docs/cli/overview

Demonstrates the shorthand alias available for global CLI installations.

```sh
pho projects ls     # same as: photon projects ls
pho whoami
```

--------------------------------

### Initialize Terminal Provider

Source: https://photon.codes/docs/spectrum-ts/providers/terminal/setup-and-usage

Basic setup to initialize the Spectrum application with the terminal provider.

```ts
import { Spectrum } from "spectrum-ts";
import { terminal } from "spectrum-ts/providers/terminal";

const app = await Spectrum({
  providers: [terminal.config()],
});

for await (const [space, message] of app.messages) {
  if (message.content.type === "text") {
    await space.send(`echo: ${message.content.text}`);
  }
}
```

--------------------------------

### GET /api/projects/

Source: https://photon.codes/docs/api-reference/projects/list-projects

Returns every project the authenticated user owns or has been added to as a member.

```APIDOC
## GET /api/projects/

### Description
Returns every project the authenticated user owns or has been added to as a member.

### Method
GET

### Endpoint
/api/projects/

### Response
#### Success Response (200)
- **projects** (array) - Projects accessible to the caller.

#### Error Response (401)
- **error** (string) - Missing or invalid access token.
```

--------------------------------

### Check Node.js Version

Source: https://photon.codes/docs/advanced-kits/imessage/getting-started

Verify that the installed Node.js version meets the minimum requirement of 18.17.

```bash
node --version
```

--------------------------------

### Get a single message by GUID

Source: https://photon.codes/docs/advanced-kits/imessage/messages

Retrieves a specific message using its GUID. Throws a NotFoundError if the message does not exist.

```ts
const message = await im.messages.get(sent.guid);

console.log(message.content.text);
```

--------------------------------

### Initialize and Use WhatsApp Client

Source: https://photon.codes/docs/advanced-kits/whatsapp/getting-started

Demonstrates how to instantiate the client with environment variables and perform basic message sending and event subscription.

```ts
import { createClient } from "@photon-ai/whatsapp-business";

const client = createClient({
  accessToken: process.env.WA_ACCESS_TOKEN!,
  phoneNumberId: process.env.WA_PHONE_NUMBER_ID!,
  appSecret: process.env.WA_APP_SECRET!,
});

await client.messages.send({
  to: "+15551234567",
  text: "Hello from the SDK!",
});

for await (const event of client.events.subscribe()) {
  if (event.type === "message") {
    console.log(event.message);
  }
}
```

--------------------------------

### Get a Chat

Source: https://photon.codes/docs/advanced-kits/imessage/chats

Retrieves chat details using a GUID. Throws a NotFoundError if the chat cannot be resolved.

```ts
const chat = await im.chats.get("any;-;alice@example.com");

console.log(chat.displayName, chat.unreadCount, chat.isGroup);
```

```jsonc
{
  "guid": "any;-;alice@example.com",  // Chat GUID used by chat and message APIs
  "displayName": "Alice",            // Display name
  "isGroup": false,                  // Whether this is a group chat
  "participants": [                  // Chat participants
    {
      "address": "alice@example.com",
      "service": "iMessage"
    }
  ],
  "service": "iMessage",             // Chat service
  "isArchived": false,               // Whether the chat is archived
  "isFiltered": false,               // Whether the system filtered this chat
  "unreadCount": 0,                  // Unread count; may be absent
  "lastMessage": {}                  // Latest message when available
}
```

--------------------------------

### Common Photon CLI Commands

Source: https://photon.codes/docs/cli/overview

Demonstrates basic usage for logging in, listing projects, setting environment variables, and managing Spectrum resources.

```sh
# Log in (opens a browser to approve the device)
photon login

# List your projects
photon projects ls

# Set a project for the current shell session
export PHOTON_PROJECT_ID=<project-id>

# Manage Spectrum resources
photon spectrum users ls
photon spectrum lines ls

# Check billing
photon billing show
```

--------------------------------

### Build Promo Launch Template with Buttons

Source: https://photon.codes/docs/advanced-kits/whatsapp/templates

Constructs a promotional launch template with a text header, text body, and both quick-reply and URL buttons. This shows how to use `.button()` and `.urlButton()` with their respective index and parameter helpers.

```typescript
const msg = template("promo_launch", "en_US")
  .header(text("Spring sale"))
  .body(text("Alice"), text("30%"))
  .button(0, payload("apply_code"))      // quick-reply button
  .urlButton(1, text("spring-30"));      // dynamic URL suffix
```

--------------------------------

### im.chats.get(guid)

Source: https://photon.codes/docs/advanced-kits/imessage/chats

Retrieves the details of a specific chat using its unique GUID.

```APIDOC
## im.chats.get(guid)

### Description
Retrieves a Chat object by its unique GUID. Throws a NotFoundError if the chat cannot be resolved.

### Parameters
- **guid** (string) - Required - The unique identifier for the chat.

### Response
- **guid** (string) - Chat GUID
- **displayName** (string) - Display name of the chat
- **isGroup** (boolean) - Whether the chat is a group chat
- **participants** (array) - List of participants
- **service** (string) - The chat service
- **isArchived** (boolean) - Whether the chat is archived
- **isFiltered** (boolean) - Whether the chat is filtered
- **unreadCount** (number) - Number of unread messages
- **lastMessage** (object) - The latest message in the chat
```

--------------------------------

### Create a New Project

Source: https://photon.codes/docs/cli/projects

Creates a new Photon project. An interactive prompt is used by default, or flags can be provided for direct configuration.

```sh
photon projects create
```

```sh
photon projects create --name "My Project" --location us-east --spectrum
```

--------------------------------

### Initialize Spectrum with Telegram

Source: https://photon.codes/docs/spectrum-ts/providers/telegram/setup

Full example showing the integration of the Telegram provider within a Spectrum application instance.

```ts
import { Spectrum } from "spectrum-ts";
import { telegram } from "spectrum-ts/providers/telegram";

const app = await Spectrum({
  projectId: process.env.PROJECT_ID!,
  projectSecret: process.env.PROJECT_SECRET!,
  providers: [
    telegram.config({
      botToken: process.env.TELEGRAM_BOT_TOKEN!,
    }),
  ],
});

for await (const [space, message] of app.messages) {
  if (message.content.type === "text") {
    await space.send(`Echo: ${message.content.text}`);
  }
}
```

--------------------------------

### Get project OpenAPI definition

Source: https://photon.codes/docs/api-reference/projects/get-project

The OpenAPI specification for the GET /projects/{projectId}/ endpoint.

```yaml
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/:
    get:
      tags:
        - projects
      summary: Get project
      description: >-
        Returns the project's display name plus, when set, its profile
        (firstName, lastName, avatarUrl). When a profile is set, the response
        also includes `imessageSynced`: true iff the project is Business-tier
        and every active dedicated iMessage Line has its current Profile
        successfully applied. Free/Pro projects ride a shared line and always
        report false. Zero active dedicated Lines on Business is considered
        synced. Requires Authorization: Basic base64(projectId:projectSecret).
      operationId: getProjectsByProjectId
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      name:
                        type: string
                      slug:
                        type: string
                      profile:
                        type: object
                        properties:
                          firstName:
                            type: string
                          lastName:
                            type: string
                          avatarUrl:
                            anyOf:
                              - type: string
                              - type: 'null'
                          imessageSynced:
                            type: boolean
                        required:
                          - firstName
                          - lastName
                          - avatarUrl
                          - imessageSynced
                        additionalProperties: false
                    required:
                      - name
                      - slug
                      - profile
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false
```

--------------------------------

### Install Local iMessage Provider

Source: https://photon.codes/docs/spectrum-ts/providers/imessage/connection-and-routing

Installs the necessary packages for local macOS iMessage integration.

```bash
bun add spectrum-ts @spectrum-ts/imessage-local
```

--------------------------------

### Authenticate with Photon CLI

Source: https://photon.codes/docs/cli/overview

Initializes the authentication process using npx.

```sh
npx @photon-ai/cli login
```

--------------------------------

### Update global CLI installation

Source: https://photon.codes/docs/cli/installation

Update the globally installed CLI package to the latest version.

```sh
npm update -g @photon-ai/cli
```

```sh
pnpm update -g @photon-ai/cli
```

```sh
yarn global upgrade @photon-ai/cli
```

```sh
bun update -g @photon-ai/cli
```

--------------------------------

### Edit an iMessage

Source: https://photon.codes/docs/advanced-kits/imessage/messages

Updates a sent message with new text. Requires the chat GUID and message GUID.

```ts
const edited = await im.messages.edit(chat.guid, sent.guid, "Corrected text", {
  backwardCompatText: "Edited: Corrected text",
});

console.log(edited.guid);
```

--------------------------------

### List Projects

Source: https://photon.codes/docs/cli/projects

Lists all available projects. Use the --json flag to get the output in JSON format.

```sh
photon projects ls
photon projects ls --json
```

--------------------------------

### Send text message using chat GUID

Source: https://photon.codes/docs/advanced-kits/imessage/getting-started

Use the resolved chat GUID to send a message.

```typescript
await im.messages.sendText(chat.guid, "Hello from the SDK");
```

--------------------------------

### Install heif2jpeg using npm

Source: https://photon.codes/docs/utilities/heif2jpeg

Install the heif2jpeg package using npm. This is the standard package manager for Node.js.

```bash
npm install heif2jpeg
```

--------------------------------

### createClient

Source: https://photon.codes/docs/advanced-kits/whatsapp/getting-started

Initializes a new WhatsApp client instance with the required authentication credentials and configuration options.

```APIDOC
## createClient

### Description
Initializes the WhatsApp client to interact with the WhatsApp Business API.

### Signature
`createClient(options: ClientOptions): WhatsAppClient`

### Parameters
- **retry** (boolean | RetryOptions) - Optional - Enable automatic retry with exponential backoff for retryable errors.
- **timeout** (number) - Optional - Default timeout in milliseconds for unary RPC calls.
```

--------------------------------

### Send an attachment in iMessage

Source: https://photon.codes/docs/advanced-kits/imessage/messages

Upload a file to receive a GUID, then use that GUID to send the attachment to a specific chat.

```ts
const uploaded = await im.attachments.upload({
  fileName: "photo.jpg",
  data: await readFile("photo.jpg"),
});

const sent = await im.messages.sendAttachment(chat.guid, uploaded.attachment.guid);

console.log(sent.guid);
```

--------------------------------

### Initialize Spectrum with project credentials

Source: https://photon.codes/docs/spectrum-ts/getting-started

Configures the Spectrum instance with project-specific credentials and an iMessage provider to listen for and respond to messages.

```ts
import { Spectrum } from "spectrum-ts";
import { imessage } from "spectrum-ts/providers/imessage";

const app = await Spectrum({
  projectId: "your-project-id",
  projectSecret: "your-project-secret",
  providers: [
    imessage.config(),
  ],
});

for await (const [space, message] of app.messages) {
  if (message.content.type === "text") {
    console.log(`[${message.platform}] ${message.sender?.id ?? "unknown"}: ${message.content.text}`);
    await space.send("hello world");
  }
}
```

--------------------------------

### Initialize Developer Profile

Source: https://photon.codes/docs/cli/profile-and-utilities

Walks you through an interactive prompt to create a developer or organization profile. Can be used non-interactively with flags.

```sh
photon profile init
```

--------------------------------

### Initialize local webhook server

Source: https://photon.codes/docs/webhooks/quickstart

Create a basic Hono server to receive POST requests at the /spectrum-webhook endpoint.

```ts
import { Hono } from 'hono';

const app = new Hono();

app.post('/spectrum-webhook', async (c) => {
  const body = await c.req.text();
  console.log('received', body.slice(0, 200));
  return c.text('ok', 200);
});

export default { port: 3000, fetch: app.fetch };
```

--------------------------------

### Install heif2jpeg using pnpm

Source: https://photon.codes/docs/utilities/heif2jpeg

Install the heif2jpeg package using pnpm. pnpm is an alternative package manager for Node.js.

```bash
pnpm add heif2jpeg
```

--------------------------------

### Install better-sqlite3 dependency

Source: https://photon.codes/docs/spectrum-ts/troubleshooting/imessage

Use this command if your package manager omits the optional better-sqlite3 dependency required for local iMessage functionality.

```bash
npm install better-sqlite3
```

--------------------------------

### Initialize Spectrum without credentials

Source: https://photon.codes/docs/spectrum-ts/getting-started

Sets up a Spectrum instance using a projectless provider like terminal, which does not require project credentials.

```ts
import { Spectrum } from "spectrum-ts";
import { terminal } from "spectrum-ts/providers/terminal";

const app = await Spectrum({
  providers: [terminal.config()],
});
```

--------------------------------

### im.attachments.downloadStream(guid)

Source: https://photon.codes/docs/advanced-kits/imessage/attachments

Initiates a stream to download an attachment by its GUID. The stream emits a header frame followed by data chunks.

```APIDOC
## im.attachments.downloadStream(guid)

### Description
Downloads an attachment as a stream. The stream provides metadata via a header frame and data via chunks. For Live Photos, the stream may include both primary and companion chunks.

### Parameters
- **guid** (string) - Required - The unique identifier of the attachment.

### Usage
```ts
for await (const frame of im.attachments.downloadStream(attachment.guid)) {
  switch (frame.type) {
    case "header":
      // Handle metadata
      break;
    case "primaryChunk":
      // Handle primary file data
      break;
    case "companionChunk":
      // Handle Live Photo companion data
      break;
  }
}
```

### Errors
- **NotFoundError**: Thrown if the attachment does not exist.
- **ValidationError (attachmentNotReady)**: Thrown if the attachment transferState is not 'finished'.
```

--------------------------------

### Install heif2jpeg using yarn

Source: https://photon.codes/docs/utilities/heif2jpeg

Install the heif2jpeg package using yarn. yarn is another popular package manager for Node.js.

```bash
yarn add heif2jpeg
```

--------------------------------

### Separate deployment entrypoints

Source: https://photon.codes/docs/spectrum-ts/providers/imessage

Use distinct composition modules for cloud and local environments to prevent unnecessary dependency bundling.

```ts
// cloud-app.ts
import { imessage } from "@spectrum-ts/imessage";

export const providers = [imessage.config()];
```

```ts
// mac-app.ts
import { localIMessage } from "@spectrum-ts/imessage-local";

export const providers = [localIMessage.config()];
```

--------------------------------

### POST /api/projects/

Source: https://photon.codes/docs/api-reference/projects/create-project

Creates a new project owned by the authenticated user. When spectrum is true, a Spectrum project is provisioned and its spectrumProjectId and projectSecret are set on the response.

```APIDOC
## POST /api/projects/

### Description
Creates a new project owned by the authenticated user. When `spectrum` is true, a Spectrum project is provisioned and its `spectrumProjectId` + `projectSecret` are set on the response.

### Method
POST

### Endpoint
/api/projects/

### Parameters
#### Request Body
- **name** (string) - Required - The name of the project.
- **location** (string) - Optional - The location of the project (e.g., "United States").
- **spectrum** (boolean) - Optional - Whether to provision a Spectrum project (default: false).
- **template** (boolean) - Optional - Whether to use a template (default: false).
- **observability** (boolean) - Optional - Whether to enable observability (default: false).
- **platforms** (array) - Optional - List of platforms (imessage, whatsapp_business, voice).

### Response
#### Success Response (200)
- **id** (string) - The project UUID.
- **name** (string) - The project name.
- **location** (string) - The project location.
- **status** (string) - The project status.
- **spectrum** (boolean) - Whether spectrum is enabled.
- **spectrumProjectId** (string) - Spectrum project ID (nullable).
- **projectSecret** (string) - Spectrum project secret (nullable).
- **template** (boolean) - Whether template is enabled.
- **observability** (boolean) - Whether observability is enabled.
- **userId** (string) - The owner user ID.
- **createdAt** (string) - Creation timestamp.
- **updatedAt** (string) - Last update timestamp.
```

--------------------------------

### im.getAttachment(guid, phoneNumber?)

Source: https://photon.codes/docs/spectrum-ts/providers/imessage/messaging-features/fetching-attachments

Retrieves an attachment by its iMessage GUID. The returned Attachment object is lazy, and calling .read() or .stream() triggers the download.

```APIDOC
## getAttachment(guid, phoneNumber?)

### Description
Retrieves a cloud iMessage attachment by its unique GUID. The method returns an Attachment object which provides methods to read or stream the file content.

### Parameters
- **guid** (string) - Required - The unique identifier of the iMessage attachment.
- **phoneNumber** (string) - Optional - The phone number used to route the request in multi-phone mode.

### Usage Example
```ts
import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(app);
const att = await im.getAttachment("p:0/GUID");

if (att) {
  console.log(att.name, att.mimeType, att.size);
  const bytes = await att.read();
}
```

### Multi-phone Usage
```ts
const att = await im.getAttachment("p:0/GUID", "+15559999999");
```
```

--------------------------------

### OpenAPI definition for Get project profile sync status

Source: https://photon.codes/docs/api-reference/projects/get-project-profile-sync-status

The OpenAPI specification defining the GET request for project profile synchronization status.

```yaml
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/profile/sync:
    get:
      tags:
        - projects
      summary: Get project profile sync status
      description: >-
        Returns current aggregate Line convergence with no sync instance ID or
        history.
      operationId: getProjectsByProjectIdProfileSync
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      projectId:
                        type: string
                      status:
                        type: string
                        enum:
                          - in_progress
                          - completed
                          - partial_failed
                          - failed
                      total:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      pending:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      synced:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      failed:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            lineId:
                              type: string
                            reason:
                              type: string
                          required:
                            - lineId
                            - reason
                          additionalProperties: false
                    required:
                      - projectId
                      - status
                      - total
                      - pending
                      - synced
                      - failed
                      - errors
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false
```

--------------------------------

### OpenAPI specification for Get subscription details

Source: https://photon.codes/docs/api-reference/billing/get-subscription-details

Defines the GET endpoint for project billing subscription status, including parameter requirements and the expected JSON response structure.

```yaml
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/billing/subscription:
    get:
      tags:
        - billing
      summary: Get subscription details
      description: >-
        Returns the current plan tier and subscription status for a project.
        Requires Authorization: Basic base64(projectId:projectSecret).
      operationId: getProjectsByProjectIdBillingSubscription
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      tier:
                        type: string
                      status:
                        anyOf:
                          - type: string
                            enum:
                              - active
                              - canceled
                              - past_due
                          - type: 'null'
                      cancel_at_period_end:
                        type: boolean
                      subscription_id:
                        anyOf:
                          - type: string
                          - type: 'null'
                      customer_id:
                        anyOf:
                          - type: string
                          - type: 'null'
                    required:
                      - tier
                      - status
                      - cancel_at_period_end
                      - subscription_id
                      - customer_id
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false
```

--------------------------------

### createClient(options)

Source: https://photon.codes/docs/advanced-kits/imessage/getting-started

Initializes the iMessage client with the required server connection details and optional configuration settings.

```APIDOC
## createClient(options)

### Description
Initializes a new client instance to interact with the iMessage API. The client requires a server address and authentication token.

### Parameters
- **address** (string) - Required - Server address in host:port format. Do not include https://.
- **token** (string) - Required - Bearer token for authentication.
- **tls** (boolean) - Optional - Encrypt the gRPC connection. Defaults to true.
- **timeout** (number) - Optional - Timeout in milliseconds for unary requests.
- **retry** (boolean | RetryOptions) - Optional - Configuration for retrying unary failures.
```

--------------------------------

### Fetch an iMessage attachment by GUID

Source: https://photon.codes/docs/spectrum-ts/providers/imessage/messaging-features/fetching-attachments

Retrieves an attachment using its GUID. Note that .read() and .stream() trigger independent downloads, so cache the result of .read() if needed multiple times.

```ts
import { imessage } from "spectrum-ts/providers/imessage";

const im = imessage(app);
const att = await im.getAttachment("p:0/GUID");

if (att) {
  console.log(att.name, att.mimeType, att.size);
  const bytes = await att.read();
}
```

--------------------------------

### Open Project in Dashboard

Source: https://photon.codes/docs/cli/projects

Opens the project's Dashboard page in the default browser. Use `--no-browser` to print the URL instead.

```sh
photon projects open
photon projects open <project-id>
photon projects open --no-browser   # prints the URL instead
```

--------------------------------

### OpenAPI Specification for Get User

Source: https://photon.codes/docs/api-reference/users/get-user

This OpenAPI 3.1.0 specification defines the GET /projects/{projectId}/users/{userId}/ endpoint for retrieving user details. It includes request parameters, authentication requirements, and response schemas.

```yaml
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/users/{userId}/:
    get:
      tags:
        - users
      summary: Get user
      description: >-
        Returns a single user by ID. Requires Authorization: Basic
        base64(projectId:projectSecret).
      operationId: getProjectsByProjectIdUsersByUserId
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      projectId:
                        type: string
                      type:
                        type: string
                        enum:
                          - shared
                          - dedicated
                      firstName:
                        anyOf:
                          - type: string
                          - type: 'null'
                      lastName:
                        anyOf:
                          - type: string
                          - type: 'null'
                      email:
                        anyOf:
                          - type: string
                          - type: 'null'
                      phoneNumber:
                        type: string
                        format: e164
                        pattern: ^\+[1-9]\d{6,14}$
                      assignedPhoneNumber:
                        type: string
                        format: e164
                        pattern: ^\+[1-9]\d{6,14}$
                      meta:
                        anyOf:
                          - type: object
                            propertyNames:
                              type: string
                            additionalProperties: {}
                          - type: 'null'
                      createdAt:
                        type: string
                    required:
                      - id
                      - projectId
                      - type
                      - firstName
                      - lastName
                      - email
                      - phoneNumber
                      - assignedPhoneNumber
                      - meta
                      - createdAt
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false

```

--------------------------------

### Configure WhatsApp Business Provider

Source: https://photon.codes/docs/spectrum-ts/providers/whatsapp-business/setup

Initializes the provider with required Meta credentials. Values can be provided directly or via environment variables.

```ts
whatsappBusiness.config({
  accessToken: "your-access-token",
  phoneNumberId: "your-phone-number-id",
  appSecret: "your-app-secret",
});
```

--------------------------------

### OpenAPI Specification for Get iMessage Info

Source: https://photon.codes/docs/api-reference/imessage/get-imessage-info

This OpenAPI specification defines the GET endpoint for retrieving iMessage service information. It outlines the request parameters, authentication requirements, and the structure of the JSON response, including the iMessage service type.

```yaml
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/imessage/:
    get:
      tags:
        - imessage
      summary: Get iMessage info
      description: >-
        Returns the iMessage service type (shared or dedicated) for the project.
        Requires Authorization: Basic base64(projectId:projectSecret).
      operationId: getProjectsByProjectIdImessage
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - shared
                          - dedicated
                    required:
                      - type
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false

```

--------------------------------

### Get Billing Sync Status OpenAPI Specification

Source: https://photon.codes/docs/api-reference/billing/get-billing-sync-status

This OpenAPI specification defines the GET /projects/{projectId}/billing/status endpoint. It outlines the request parameters, authentication method, and the structure of the JSON response, including possible sync statuses.

```yaml
openapi: 3.1.0
info:
  title: Spectrum Cloud External API
  description: Client-facing API for Spectrum Cloud.
  version: 1.0.0
servers:
  - url: https://spectrum.photon.codes
security: []
tags:
  - name: billing
    description: Billing and subscription operations
  - name: imessage
    description: iMessage platform operations
  - name: lines
    description: Phone line enumeration across platforms
  - name: platforms
    description: Platform management operations
  - name: users
    description: User operations
  - name: voice
    description: Voice platform operations
  - name: webhooks
    description: Webhook registration for receiving Spectrum events
  - name: whatsapp-business
    description: WhatsApp Business platform operations
  - name: slack
    description: Slack platform operations
paths:
  /projects/{projectId}/billing/status:
    get:
      tags:
        - billing
      summary: Get billing sync status
      description: >-
        Returns the project's async-billing sync state. After POST/DELETE
        /lines, poll this endpoint until `syncStatus !== 'syncing'` to read the
        final proration. Requires Authorization: Basic
        base64(projectId:projectSecret).
      operationId: getProjectsByProjectIdBillingStatus
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            pattern: >-
              ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              schema:
                type: object
                properties:
                  succeed:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      syncStatus:
                        type: string
                        enum:
                          - in_sync
                          - syncing
                          - failed
                      lastSyncedAt:
                        anyOf:
                          - type: string
                          - type: 'null'
                      error:
                        anyOf:
                          - type: string
                          - type: 'null'
                      quantity:
                        type: number
                      lastProrationAmount:
                        anyOf:
                          - type: number
                          - type: 'null'
                    required:
                      - syncStatus
                      - lastSyncedAt
                      - error
                      - quantity
                      - lastProrationAmount
                    additionalProperties: false
                required:
                  - succeed
                  - data
                additionalProperties: false

```

--------------------------------

### Client Initialization Signature

Source: https://photon.codes/docs/advanced-kits/whatsapp/getting-started

The signature for creating a new WhatsApp client instance.

```ts
const client = createClient(options: ClientOptions): WhatsAppClient;
```

--------------------------------

### Enable a Spectrum Platform

Source: https://photon.codes/docs/cli/spectrum

Enable a specific messaging platform for your project by providing its name.

```sh
photon spectrum platforms enable <platform-name>
```

--------------------------------

### Register and use a custom platform

Source: https://photon.codes/docs/spectrum-ts/custom-platforms

Configure a custom platform with an API key and perform operations like user retrieval and message sending.

```ts
const app = await Spectrum({
  providers: [
    myPlatform.config({ apiKey: process.env.MY_KEY! }),
  ],
});

const mine = myPlatform(app);
const user = await mine.user("user-123");
const space = await mine.space.create(user);

await space.send("Hello from my custom platform.");
```

--------------------------------

### GET /api/auth/oauth2/userinfo

Source: https://photon.codes/docs/api-reference/oauth

Retrieves information about the authenticated user.

```APIDOC
## GET /api/auth/oauth2/userinfo

### Description
Retrieves information about the authenticated user.

### Method
GET

### Endpoint
https://app.photon.codes/api/auth/oauth2/userinfo
```

--------------------------------

### im.messages.get(guid)

Source: https://photon.codes/docs/advanced-kits/imessage/messages

Retrieves a single message by its unique identifier.

```APIDOC
## im.messages.get(guid)

### Description
Retrieves a single message using its GUID. Throws a NotFoundError if the message does not exist.

### Parameters
- **guid** (string) - Required - The unique identifier of the message.
```

--------------------------------

### Show Project Details

Source: https://photon.codes/docs/cli/projects

Displays details for a specific project. If no project ID is provided, it defaults to the PHOTON_PROJECT_ID environment variable.

```sh
photon projects show
photon projects show <project-id>
```

--------------------------------

### im.attachments.get

Source: https://photon.codes/docs/advanced-kits/imessage/attachments

Retrieves metadata for a specific attachment using its GUID.

```APIDOC
## im.attachments.get

### Description
Retrieves metadata for an attachment by its GUID. This is used to inspect file state, display information, or confirm readiness.

### Parameters
- **guid** (string) - Required - The unique identifier of the attachment.

### Response
- **guid** (string) - Attachment GUID.
- **fileName** (string) - Stored file name.
- **mimeType** (string) - Server-detected MIME type.
- **uti** (string) - Apple Uniform Type Identifier.
- **totalBytes** (number) - File size in bytes.
- **transferState** (string) - Current transfer state (pending, transferring, failed, finished, unknown).
- **isOutgoing** (boolean) - Whether uploaded by the current account.
- **isHidden** (boolean) - Whether hidden by Apple.
- **isSticker** (boolean) - Whether used as a sticker.
- **companionKind** (string) - Companion kind if applicable.
- **originalGuid** (string) - Original attachment GUID if applicable.
```

--------------------------------

### im.chats.markRead(guid)

Source: https://photon.codes/docs/advanced-kits/imessage/chats

Marks all messages in the specified chat as read.

```APIDOC
## im.chats.markRead(guid)

### Description
Marks the chat as read. Safe to call even if there are no unread messages.

### Parameters
- **guid** (string) - Required - The unique identifier for the chat.
```
Tokens:
Raw