A modular TypeScript SDK for interacting with the Subspace protocol on Arweave.
npm install @subspace-protocol/sdkimport{Subspace}from'@subspace-protocol/sdk';// Initialize the SDKconstsubspace=newSubspace({CU_URL: 'https://cu.arnode.asia',GATEWAY_URL: 'https://arweave.net',owner: 'your-wallet-address',signer: yourAoSigner,// Optional: for write operations// jwk: yourJWK, // Alternative: provide JWK for signing});// Use the modular managersconstprofile=awaitsubspace.user.getProfile('user-id');constserver=awaitsubspace.server.getServer('server-id');constmessages=awaitsubspace.server.getMessages('server-id',{channelId: 'channel-id',limit: 50});The SDK is built with a modular architecture:
Subspace: Main class that coordinates all managersConnectionManager: Handles AO connections and communication- Domain Managers: Specialized managers for different functionality areas
Handles user profiles, friends, direct messages, and user actions.
// Profile operationsconstprofile=awaitsubspace.user.getProfile('user-id');constprofiles=awaitsubspace.user.getBulkProfiles(['user1','user2']);awaitsubspace.user.updateProfile({pfp: 'new-pfp-url'});// Friend operationsawaitsubspace.user.sendFriendRequest('friend-id');awaitsubspace.user.acceptFriendRequest('friend-id');// Server operationsawaitsubspace.user.joinServer('server-id');awaitsubspace.user.leaveServer('server-id');// Direct messagesconstdms=awaitsubspace.user.getDMs('dm-process-id',{limit: 50});awaitsubspace.user.sendDM('dm-process-id',{content: 'Hello!'});Handles server operations, channels, categories, roles, and messages.
// Server operationsconstserver=awaitsubspace.server.getServer('server-id');constserverId=awaitsubspace.server.createServer({name: 'My Server',logo: 'logo-url',description: 'Server description'});// Member operationsconstmembers=awaitsubspace.server.getAllMembers('server-id');constmember=awaitsubspace.server.getMember('server-id','user-id');awaitsubspace.server.updateMember('server-id',{userId: 'user-id',nickname: 'New Nickname'});// Channel operationsawaitsubspace.server.createChannel('server-id',{name: 'general',categoryId: 'category-id',type: 'text'});// Message operationsconstmessages=awaitsubspace.server.getMessages('server-id',{channelId: 'channel-id',limit: 50});awaitsubspace.server.sendMessage('server-id',{channelId: 'channel-id',content: 'Hello, world!'});Handles bot creation, management, and deployment.
// Bot operationsconstbotId=awaitsubspace.bot.createBot({name: 'My Bot',description: 'A helpful bot',source: 'bot-source-code'});constbot=awaitsubspace.bot.getBot('bot-id');awaitsubspace.bot.addBotToServer({serverId: 'server-id',botId: 'bot-id'});interfaceConnectionConfig{CU_URL?: string;// Compute Unit URLGATEWAY_URL?: string;// Arweave Gateway URLsigner?: AoSigner;// AO Signer for transactionsjwk?: JWKInterface;// JWK for signingowner?: string;// Owner address}// Update configurationsubspace.updateConfig({CU_URL: 'https://cu.ardrive.io'});// Switch compute unitsubspace.switchCu();// Get connection infoconstinfo=subspace.getConnectionInfo();console.log(info.cuUrl,info.hasJwk,info.hasSigner);// Use managers independentlyimport{UserManager,ServerManager,ConnectionManager}from'@subspace-protocol/sdk';constconnectionManager=newConnectionManager({CU_URL: 'https://cu.arnode.asia'});constuserManager=newUserManager(connectionManager);constserverManager=newServerManager(connectionManager);The SDK exports comprehensive TypeScript types:
importtype{// Core typesSubspace,ConnectionConfig,Tag,MessageResult,AoSigner,// User typesProfile,Notification,Friend,DMMessage,DMResponse,// Server typesServer,Member,Channel,Category,Role,Message,MessagesResponse,// Bot typesBot,BotInfo}from'@subspace-protocol/sdk';The SDK provides comprehensive error handling:
try{constprofile=awaitsubspace.user.getProfile('user-id');}catch(error){if(error.message.includes('No signer available')){console.error('Signer required for this operation');}else{console.error('Failed to get profile:',error);}}If you're migrating from the legacy SDK, here are the key changes:
// Static methodsconstprofile=awaitSubspace.getProfile('user-id');constserver=awaitSubspace.getServer('server-id');awaitSubspace.sendMessage(serverId,{content: 'Hello'});// Instance methods with managersconstsubspace=newSubspace(config);constprofile=awaitsubspace.user.getProfile('user-id');constserver=awaitsubspace.server.getServer('server-id');awaitsubspace.server.sendMessage(serverId,{content: 'Hello'});# Install dependencies
npm install
# Build the SDK
npm run build
# Run tests
npm test# Start development mode
npm run devMIT License - see LICENSE file for details.