API Reference

Complete reference for the Scc client and all sub-APIs.

import { Scc, MessageChannel, Server, SccError } from 'scc-opensdk';

`Scc`

Constructor

const scc = new Scc({
  userData: string,    // required — vault root path
  username: string,    // required
  password: string,    // required
  vault?: string,      // unlock name, default: username
  host?: string,       // default: 'direct.scc.is'
  version?: string,    // default: '0.7.105'
  nativePath?: string, // override scc-node.node path
});

Static methods

`Scc.connect(options)` → `Promise<Scc>`

Creates a client, runs the full auth + connect sequence, returns a ready instance.

const scc = await Scc.connect({ userData, username, password });

Instance methods

Method	Returns	Description
`connect()`	`Promise<Scc>`	Login, knock, WebSocket connect
`disconnect()`	`Promise<void>`	Close WebSocket
`close()`	`Promise<void>`	Disconnect + kill session process
`raw(command, args?)`	`Promise<any>`	Direct native invoke

Instance properties

Property	Type	Description
`identity`	`IdentityAPI`	Account, settings, registration
`friends`	`FriendsAPI`	Friend roster
`messages`	`MessagesAPI`	Channel factory
`groups`	`GroupsAPI`	Group management
`servers`	`ServersAPI`	Server management
`events`	`EventBus`	Native event subscriptions
`username`	`string`	Configured username
`host`	`string`	Relay hostname
`version`	`string`	App version
`nativePath`	`string`	Resolved scc-node.node path
`isConnected`	`boolean`	WebSocket connected

`IdentityAPI` — `scc.identity`

Method	Args	Returns	Description
`login()`	—	`Identity`	Server authentication
`register(opts)`	`{ username?, password?, displayName? }`	`Identity`	Create new account
`unlock(passphrase, name)`	strings	`void`	Decrypt local vault
`lock()`	—	`void`	Lock vault
`getSettings()`	—	`Settings`	Read app settings
`updateSettings(patch)`	`object`	`Settings`	Write settings
`enableTor()`	—	`Settings`	Enable built-in Tor
`useSocksProxy(proxy)`	`string`	`Settings`	Set SOCKS proxy

Identity object

Returned by login() and register():

{
  username: string;
  fingerprint: string;   // "xxxx-xxxx-xxxx-xxxx"
  public_key: string;    // base64 Ed25519
  name: string;          // display name
}

`FriendsAPI` — `scc.friends`

Method	Args	Returns	Description
`list()`	—	`Friend[]`	All friends
`add(username)`	`string`	`FriendRequest`	Send friend request
`respond(requestId, accept?)`	`string, boolean`	`void`	Accept/deny request
`remove(username)`	`string`	`void`	Remove friend
`block(username)`	`string`	`void`	Block user
`unblock(username)`	`string`	`void`	Unblock user
`listBlocked()`	—	`BlockedUser[]`	List blocked

Friend object

{
  username: string;
  display_name: string;
  pubkey: string;           // Ed25519 public key
  dh_pubkey: string;        // X25519 for DM key agreement
  request_id?: string;      // UUID, for respond()
  state: 'pending_incoming' | 'pending_outgoing' | 'accepted';
}

`MessagesAPI` — `scc.messages`

Factory for MessageChannel instances. Does not send messages directly.

Method	Args	Returns	Description
`dm(username)`	`string`	`MessageChannel`	DM to `@username`
`group(groupId)`	`string`	`MessageChannel`	Group channel `g:<id>`
`channel(address)`	`string`	`MessageChannel`	Any raw address

`MessageChannel`

Represents a single conversation endpoint.

Properties

Property	Type	Description
`address`	`string`	Channel address (`@user`, `g:id`, `srv:...`)

Methods

Method	Args	Returns	Description
`send(body, opts?)`	`string, SendOptions`	`string`	Send message, returns message UUID
`history()`	—	`Message[]`	Channel history
`typing()`	—	`void`	Send typing indicator
`edit(messageId, body)`	`string, string`	`void`	Edit own message
`delete(messageId)`	`string`	`void`	Delete message
`pin(messageId, pinned?)`	`string, boolean`	`void`	Pin/unpin message
`react(messageId, symbol, add?)`	`string, string, boolean`	`void`	Add/remove reaction

SendOptions

{
  attachments?: Attachment[];  // default: []
  replyTo?: string | null;     // message UUID
  system?: string | null;      // system message type (avoid in bots)
  once?: boolean;              // view-once message
  onceViews?: number;          // default: 1
  onceSecs?: number;           // default: 0
}

Message object

Received via scc.events.on('message', ...):

{
  id: string;              // UUID
  channel: string;
  body: string;
  user: string;            // display name
  pubkey: string;
  fingerprint: string;
  ts: number;              // Unix seconds
  self: boolean;
  verified: boolean;
  edited: boolean;
  pinned: boolean;
  attachments: Attachment[];
  reply_to: string | null;
  system: string | null;
  reactions: Reaction[];
  first_seen: boolean;
}

`GroupsAPI` — `scc.groups`

Method	Args	Returns	Description
`list()`	—	`Group[]`	All groups
`create(name, members?)`	`string, string[]`	`MessageChannel`	Create group
`addMember(groupId, username)`	`string, string`	`void`	Add member
`removeMember(groupId, username)`	`string, string`	`void`	Remove member
`rename(groupId, name)`	`string, string`	`void`	Rename group
`leave(groupId)`	`string`	`void`	Leave group

`ServersAPI` — `scc.servers`

Method	Args	Returns	Description
`list()`	—	`Server[]`	Joined servers
`get(serverId)`	`string`	`Server`	Get by ID
`create(name)`	`string`	`Server`	Create new server
`join(inviteLink)`	`string`	`Server`	Join via invite
`refresh()`	—	`void`	Sync from relay

`Server`

Returned by servers.create(), servers.join(), servers.get().

Properties

Property	Type	Description
`id`	`string`	Server ID (`s_...`)
`name`	`string`	Display name
`owner`	`string`	Owner pubkey (base64)
`isOwner`	`boolean`	You own this server
`role`	`string`	Your role (`owner`, `member`, role ID)
`roles`	`RoleDef[]`	Role definitions
`members`	`string[]`	Member pubkeys
`data`	`object`	Raw server object
`channels`	`ServerChannels`	Channel sub-API
`invites`	`ServerInvites`	Invite sub-API
`moderation`	`ServerModeration`	Moderation sub-API

Methods

Method	Args	Returns	Description
`refresh()`	—	`Server`	Reload from relay
`update(fields)`	`object`	`Server`	Update server metadata
`audit()`	—	`AuditEntry[]`	Audit log
`leave()`	—	`void`	Leave server

`server.channels`

Method	Args	Returns
`list()`	—	`ChannelInfo[]`
`findByName(name)`	`string`	`ChannelInfo \| null`
`open(channelId)`	`string`	`Promise<MessageChannel>`
`openNamed(name)`	`string`	`Promise<MessageChannel>`

`server.invites`

Method	Args	Returns
`create({ expiresIn, maxUses, note })`	object	`Invite`
`list()`	—	`Invite[]`
`revoke(code)`	`string`	`void`

`server.moderation`

Method	Args	Description
`kick(target)`	username	Remove member (can rejoin)
`ban(target)`	username	Permanently ban
`mute(target, until?)`	username, timestamp?	Mute member
`unmute(target)`	username	Remove mute
`addRole(target, roleId)`	username, role ID	Assign role
`removeRole(target, roleId)`	username, role ID	Remove role
`setRole(target, roleId)`	username, role ID	Replace all roles
`setNick(target, nick)`	username, string	Set nickname

`EventBus` — `scc.events`

Method	Args	Returns	Description
`on(event, fn)`	`string, function`	`unsubscribe`	Subscribe to event
`off(event, fn)`	`string, function`	`void`	Unsubscribe
`once(event, fn)`	`string, function`	`unsubscribe`	Subscribe once

See Events for all event names and payloads.

Errors

import { SccError, SccTimeoutError } from 'scc-opensdk';

Class	When
`SccError`	Native command failed (`error` property has message)
`SccTimeoutError`	Command timed out after 60s
`SccConnectionError`	Connection-level failure

try {
  await scc.messages.dm('nobody').send('hi');
} catch (e) {
  if (e instanceof SccError) {
    console.error('SCC error:', e.message, 'command:', e.command);
  }
}

Common error strings:

Error	Meaning
`unknown channel`	Not friends / not in group / channel not opened
`no such account`	Username doesn't exist
`you don't have permission for that`	Missing server role permission
`server not joined`	Not a member of that server
`registration failed (429)`	Rate limited — use Tor mode

Legacy `SccClient`

Deprecated alias for Scc with flat methods (sendMessage, createServer, etc.). New code should use Scc and namespaced APIs.

import { SccClient } from 'scc-opensdk';  // still works

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Scc

Constructor

Static methods

Scc.connect(options) → Promise<Scc>

Instance methods

Instance properties

IdentityAPI — scc.identity

Identity object

FriendsAPI — scc.friends

Friend object

MessagesAPI — scc.messages

MessageChannel

Properties

Methods

SendOptions

Message object

GroupsAPI — scc.groups

ServersAPI — scc.servers

Server

Properties

Methods

server.channels

server.invites

server.moderation

EventBus — scc.events

Errors

Legacy SccClient

`Scc`

`Scc.connect(options)` → `Promise<Scc>`

`IdentityAPI` — `scc.identity`

`FriendsAPI` — `scc.friends`

`MessagesAPI` — `scc.messages`

`MessageChannel`

`GroupsAPI` — `scc.groups`

`ServersAPI` — `scc.servers`

`Server`

`server.channels`

`server.invites`

`server.moderation`

`EventBus` — `scc.events`

Legacy `SccClient`