Socialkit TS SDK

[!WARNING]
This SDK is still a work-in-progress. This is the only source of documentation as we finalize the SDK and accompanying resources.

To understand the code better, look through the repository and provided types.

Installation

This SDK is available on NPM, you can install it using your preferred package manager.

npm install @magmalayer/socialkit

Description

Socialkit TS SDK is a complete rewrite of our original JS SDK.
As Socialkit and its usage scaled, so did the demand for a better DX at scale. This SDK is made to support development at scale by providing types and a more abstract view of Socialkit internals.

Migration from JS SDK

[!IMPORTANT] A complete migration guide will be provided together with other resources once this SDK reaches beta.

We recognize the annoyance of breaking backward compatibility, however, in order to make the future of Socialkit development simpler and leaner we had to do it.

The majority of functions are named the same, however, their signatures have changed.

[!IMPORTANT] Socialkit TS SDK no longer provides errors as a response. You need to catch it using try{}catch{} or with a provided catchError utility method.

Sample usage

Once the SDK is deemed finalized we will provide a complete documentation rewrite.

Initialize the SDK

import { Socialkit } from "@magmalayer/socialkit";

// Use Socialkit defaults
const socialkit = new Socialkit({});

// Disable encryption, do not connect to Encryption nodes
const socialkit = new Socialkit({ encryption: false });

// Choose your own Ceramic Storage gateway
const socialkit = new Socialkit({
  storage: {
    gateway: "...",
  },
});

Catching errors

When using the new SDK you have 2 main options to catch errors.

The third option is to not catch errors at all.

try / catch

Standard try/catch practices apply.

let post
try{
    post = await socialkit.createPost(...)
}catch(error){
    console.log("Error", error)
}

console.log("Result", post)

catchError

This is a utility method provided by Socialkit, originally implemented in Radash.
We've modified the call signature to make it more convenient for our use case.

import { catchError } from "@magmalayer/socialkit"

const [post, error] = await catchError(
    () => socialkit.createPost(...)
)

if(error){
    console.warn("Error", error)
}

console.log("Result", post)

Connection

Our SDK now exports multiple Authentication providers. These replace the old { chain, provider } methodology.

Scopes

Socialkit TS SDK allows you to define the SDK to authenticate the user with, options are storage and encryption.

import { SocialkitResources } from "@magmalayer/socialkit";

// SocialkitResources.encryption
// SocialkitResources.storage

EVM

import { Socialkit, SocialkitResources } from "@magmalayer/socialkit"
import { SocialkitEVMAuth } from "@magmalayer/socialkit/auth"

// Browser provider
const provider = window.ethereum

// Ethers provider
const provider = new Wallet(...)

// Socialkit Authenticator
const auth = new SocialkitEVMAuth(provider)
const authResult = await socialkit.connectUser({ auth })

// Wait for the user profile to be indexed
await authResult.waitIndexing()

console.log({ authResult })

// By default all available scopes will be authenticated
// In case a scope is already authenticated it will *not* be removed
// Authenticate storage only
const authResult = await socialkit.connectUser({ auth, scopes: [ SocialkitResources.storage ]})

Check if a user is connected

This method always returns true/false.

// Check if any user is connected
const connected = await socialkit.isUserConnected();

// Check if a user with the specified wallet address is connected
const connected = await socialkit.isUserConnected("0x00...");

Get the currently connected user

This method either returns the currently connected user (SocialkitConnectResult) or false.

// Get the currently connected user
const currentUser = await socialkit.getConnectedUser();
if (!currentUser) {
  // Notify the user or reconnect
  throw "There is no active user session.";
}

console.log({ currentUser });

Indexing

All methods that create or modify content, expose a waitIndexing method in their result. This allows you to guarantee Socialkit' indexing nodes indexed and store the new content.

This has been done to allow quicker UI updates in case you don't care about the status of indexing or are handling multiple actions at once.

import { MethodStatuses } from "@magmalayer/socialkit"

// Create a stream
const post = await socialkit.createPost({ ... })

// Wait for the stream to get indexed
const postIndexingResult = await post.waitIndexing()
// Alternatively you can check for the error field, as such: if ("error" in postIndexingResult)
if(postIndexingResult.status !== MethodStatuses.ok){
  throw `There was an error indexing post (${post.id}). Error: ${postIndexingResult.error}`
}

console.log(`Post (${post.id}) successfully indexed`, postIndexingResult.result)

// Fetch the post from Socialkit nodes
const newPost = await socialkit.getPost(post.id)

Primitives (schemas)

All Socialkit Ceramic schemas are auto-generated as types. They are used when creating or updating content such as posts or contexts.

Indexed content has different types due to additional metadata, formatting and social graph additions.

You can auto-generated schemas here.
The index of our schema streams is here.
Indexed content types are here.

Posts

Create a post

const post = await socialkit.createPost({
  body: "This is some content",
  context: "kjsd...ksx",
});

console.log("Created post:", post.id);

await post.waitIndexing();

console.log("Indexed post:", post.id);

Create an encrypted post

import type { DIDPkh } from "@magmalayer/socialkit";

// Create an encrypted post that only the current user can read
// User *must* be authenticated with encryption scopes
const encryptedPost = await socialkit.createPost({
  body: "This is content which will be encrypted",
  encryptionRules: [
    {
      type: "dids",
      dids: [socialkit.user.did as DIDPkh],
    },
  ],
});

console.log("Created an encrypted post:", encryptedPost.id);

await encryptedPost.waitIndexing();

console.log("Indexed an encrypted post", encryptedPost.id);

Get a post

// By default, all posts will be decrypted silently (won't throw an error if unable to decrypt)
const post = await socialkit.getPost("post_id");

// Disable post decryption
const post = await socialkit.getPost("post_id", { decryptSilently: false });

console.log({ post });

// Either of these fields can be null depending on initial post's state
console.log({ decrypted: post.body.plain, encrypted: post.body.encrypted });