@cloudillo/types

@cloudillo/types

TypeScript type definitions for Cloudillo with runtime validation using @symbion/runtype.

Installation

pnpm add @cloudillo/types

Core Types

Profile

User or community profile information.

import type { Profile } from '@cloudillo/types'

const profile: Profile = {
  idTag: 'alice@example.com',
  name: 'Alice Johnson',
  profilePic: '/file/b1~abc123'
}

Fields:

  • idTag: string - Unique identity (DNS-based)
  • name?: string - Display name
  • profilePic?: string - Profile picture URL

Action

Represents a social action or activity.

import type { Action } from '@cloudillo/types'

const action: Action = {
  actionId: 'act_123',
  type: 'POST',
  issuerTag: 'alice@example.com',
  content: {
    text: 'Hello, world!',
    title: 'My First Post'
  },
  createdAt: 1735000000,
  status: 'A'
}

Fields:

  • actionId: string - Unique action identifier
  • type: ActionType - Type of action (POST, CMNT, REACT, etc.)
  • issuerTag: string - Who created the action
  • content?: unknown - Action-specific content
  • createdAt: number - Unix timestamp (seconds)
  • status?: ActionStatus - P/A/R/C/N
  • subType?: string - Action subtype/category
  • parentId?: string - Parent action (for threads)
  • rootId?: string - Root action (for deep threads)
  • audienceTag?: string - Target audience
  • subject?: string - Subject/target (e.g., who to follow)
  • attachments?: string[] - File IDs
  • expiresAt?: number - Expiration timestamp

ActionType

Literal union of all action types.

import type { ActionType } from '@cloudillo/types'

const type: ActionType =
  | 'CONN' // Connection request
  | 'FLLW' // Follow user
  | 'POST' // Create post
  | 'ACK'  // Acknowledgment
  | 'REPOST' // Repost/share
  | 'SHRE' // Share resource
  | 'CMNT' // Comment
  | 'REACT' // Reaction
  | 'RSTAT' // Reaction statistics
  | 'MSG' // Message
  | 'FSHR' // File share

ActionStatus

Action status enumeration.

import type { ActionStatus } from '@cloudillo/types'

const status: ActionStatus =
  | 'P' // Pending
  | 'A' // Active/Accepted
  | 'R' // Rejected
  | 'C' // Cancelled
  | 'N' // None/Neutral

NewAction

Data for creating a new action.

import type { NewAction } from '@cloudillo/types'

const newAction: NewAction = {
  type: 'POST',
  content: {
    text: 'Hello!',
    title: 'Greeting'
  },
  attachments: ['file_123']
}

Fields:

  • type: string - Action type
  • subType?: string - Action subtype
  • parentId?: string - Parent action ID
  • rootId?: string - Root action ID
  • audienceTag?: string - Target audience
  • content?: unknown - Action content
  • attachments?: string[] - File IDs
  • subject?: string - Subject/target
  • expiresAt?: number - Expiration time

ActionView

Extended action with resolved references and statistics.

import type { ActionView } from '@cloudillo/types'

const actionView: ActionView = {
  actionId: 'act_123',
  type: 'POST',
  issuerTag: 'alice@example.com',
  issuer: {
    idTag: 'alice@example.com',
    name: 'Alice Johnson',
    profilePic: '/file/b1~abc'
  },
  content: { text: 'Hello!' },
  createdAt: 1735000000,
  stat: {
    reactions: 5,
    comments: 3,
    ownReaction: 'LOVE'
  }
}

Additional Fields:

  • issuer: Profile - Resolved issuer profile
  • audience?: Profile - Resolved audience profile
  • stat?: ActionStat - Statistics

FileView

File metadata with owner information.

import type { FileView } from '@cloudillo/types'

const file: FileView = {
  fileId: 'f1~abc123',
  status: 'M',
  contentType: 'image/png',
  fileName: 'photo.png',
  fileTp: 'BLOB',
  createdAt: new Date('2025-01-01'),
  tags: ['vacation', 'beach'],
  owner: {
    idTag: 'alice@example.com',
    name: 'Alice'
  }
}

Fields:

  • fileId: string - File identifier
  • status: 'P' | 'M' - Pending or Metadata-ready
  • contentType: string - MIME type
  • fileName: string - Original filename
  • fileTp?: string - File type (CRDT/RTDB/BLOB)
  • createdAt: string | Date - Creation time
  • tags?: string[] - Tags
  • owner?: Profile - Owner profile
  • preset?: string - Image preset configuration

Runtime Validation

All types include runtime validators using @symbion/runtype:

import { ProfileValidator, ActionValidator } from '@cloudillo/types'

// Validate data at runtime
const data = await api.me.get()

if (ProfileValidator.validate(data)) {
  // TypeScript knows data is a valid Profile
  console.log(data.idTag)
} else {
  console.error('Invalid profile data')
}

Type Guards

Use type guards to check types at runtime:

import { isAction, isProfile } from '@cloudillo/types'

function processData(data: unknown) {
  if (isAction(data)) {
    console.log('Action:', data.type)
  } else if (isProfile(data)) {
    console.log('Profile:', data.idTag)
  }
}

Enum Constants

Action Types

import { ACTION_TYPES } from '@cloudillo/types'

console.log(ACTION_TYPES)
// ['CONN', 'FLLW', 'POST', 'ACK', 'REPOST', 'SHRE', 'CMNT', 'REACT', 'RSTAT', 'MSG', 'FSHR']

// Use in UI
{ACTION_TYPES.map(type => (
  <option key={type} value={type}>{type}</option>
))}

Action Statuses

import { ACTION_STATUSES } from '@cloudillo/types'

console.log(ACTION_STATUSES)
// ['P', 'A', 'R', 'C', 'N']

See Also