Skip to main content

Cookbook

Common recipes for building with near-social-js.

For AI Assistants

Download the condensed context file: LLM.txt

Profiles​

Get a Profile​

import { Social } from 'near-social-js';

const social = new Social();
const profile = await social.getProfile('alice.near');

console.log(profile?.name);        // "Alice"
console.log(profile?.description); // "Builder on NEAR"
console.log(profile?.image);       // { ipfs_cid: "..." }

Update a Profile​

const tx = await social.setProfile('alice.near', {
  name: 'Alice',
  description: 'Building on NEAR',
  image: { ipfs_cid: 'bafkrei...' },
  linktree: { twitter: 'alice', github: 'alice' },
  tags: { developer: '', rust: '' },
});
await tx.send();

Posts​

Create a Post​

Posts automatically extract @mentions and #hashtags, sending notifications to mentioned users and indexing hashtags for discovery.

const tx = await social.createPost('alice.near', {
  text: 'Hello @bob.near! Check out #near #blockchain 🚀',
  type: 'md',
});
await tx.send();
// Bob will receive a mention notification
// Post will be discoverable via #near and #blockchain feeds

Create a Post with Image​

const tx = await social.createPost('alice.near', {
  text: 'Check out this cool image!',
  type: 'md',
  image: { ipfs_cid: 'bafybei...' },
  // or use URL: image: { url: 'https://example.com/image.png' }
});
await tx.send();

Get a Post​

const post = await social.getPost('alice.near', 123456789);
console.log(post?.text);  // "Hello @bob.near! Check out #near..."
console.log(post?.type);  // "md"

Get a Post with Comments​

const postWithComments = await social.getPost('alice.near', 123456789, {
  comments: true,
});
console.log(postWithComments?.comments); // Array of comment entries

Comments​

Create a Comment​

Comments also auto-extract @mentions and #hashtags. The post author is automatically notified.

const item = {
  type: 'social',
  path: 'bob.near/post/main',
  blockHeight: 123456789,
};

const tx = await social.createComment('alice.near', {
  item,
  text: 'Great post @bob.near! #awesome',
});
await tx.send();
// Bob receives a comment notification

Get Comments for a Post​

const comments = await social.getComments({
  type: 'social',
  path: 'bob.near/post/main',
  blockHeight: 123456789,
});
// Array of index entries with accountId and blockHeight

Social Graph​

Follow an Account​

Following now automatically sends a notification to the followed account.

const tx = await social.follow('alice.near', 'bob.near');
await tx.send();
// Bob receives a follow notification

Unfollow an Account​

const tx = await social.unfollow('alice.near', 'bob.near');
await tx.send();

Get Following​

const following = await social.getFollowing('alice.near');
// { "bob.near": "", "charlie.near": "" }

Get Followers​

const followers = await social.getFollowers('alice.near');
// [{ accountId: "dave.near" }, { accountId: "eve.near" }]

Likes​

Like a Post​

Liking now automatically sends a notification to the post author.

const item = {
  type: 'social',
  path: 'bob.near/post/main',
  blockHeight: 123456789,
};

const tx = await social.like('alice.near', item);
await tx.send();
// Bob receives a like notification

Unlike a Post​

const tx = await social.unlike('alice.near', item);
await tx.send();

Get Likes​

const likes = await social.getLikes(item);
// Array of index entries

Reposts​

Repost Content​

Reposting notifies the original author.

const item = {
  type: 'social',
  path: 'bob.near/post/main',
  blockHeight: 123456789,
};

const tx = await social.repost('alice.near', item);
await tx.send();
// Bob receives a repost notification

Get Reposts​

const reposts = await social.getReposts(item);
// Array of index entries showing who reposted

Feeds​

Get Account Feed​

const feed = await social.getAccountFeed('alice.near', {
  limit: 20,
  order: 'desc',
});
// Array of IndexEntry with accountId and blockHeight

Get Account Feed with Replies​

// Include both posts and comments/replies made by the account
const feedWithReplies = await social.getAccountFeed('alice.near', {
  limit: 20,
  order: 'desc',
  includeReplies: true,
});
// Returns combined and sorted posts + comments

Get Hashtag Feed​

const nearPosts = await social.getHashtagFeed('near', {
  limit: 20,
  order: 'desc',
});
// Posts tagged with #near

Get Activity Feed​

const activityFeed = await social.getActivityFeed({
  limit: 50,
  order: 'desc',
});
// All recent posts across the network

Get Mentioned Feed​

const mentions = await social.getMentionedFeed('alice.near', {
  limit: 20,
});
// Posts/comments where alice.near was @mentioned

Notifications​

Get Notifications​

const notifications = await social.getNotifications('alice.near', {
  limit: 50,
  order: 'desc',
});

// Returns notifications for:
// - mentions (@alice.near)
// - likes on your posts
// - comments on your posts
// - new followers
// - reposts of your content
// - pokes

notifications.forEach((n) => {
  console.log(`${n.accountId} - ${n.value.type}`);
  // "bob.near - like"
  // "charlie.near - mention"
  // "dave.near - follow"
});

Send a Custom Notification​

const tx = await social.notify('alice.near', 'bob.near', undefined, 'custom');
await tx.send();

Poke Someone​

const tx = await social.poke('alice.near', 'bob.near');
await tx.send();
// Bob receives a poke notification

Mention & Hashtag Extraction​

Extract Mentions from Text​

import { extractMentions } from 'near-social-js';

const text = 'Hello @alice.near and @bob.near!';
const mentions = extractMentions(text);
// ['alice.near', 'bob.near']

Extract Hashtags from Text​

import { extractHashtags } from 'near-social-js';

const text = 'Building on #near #blockchain #web3';
const hashtags = extractHashtags(text);
// ['near', 'blockchain', 'web3']

Build Notification Data​

import { buildNotifications } from 'near-social-js';

const mentions = ['alice.near', 'bob.near'];
const item = {
  type: 'social',
  path: 'charlie.near/post/main',
  blockHeight: 12345,
};

const notificationData = buildNotifications(mentions, item);
// { notify: '...' } - JSON stringified notification index data

Deleting Data​

Delete Keys with Null Values​

To delete a key from the social DB, set its value to null:

const tx = await graph.set({
  signerId: 'alice.near',
  data: {
    'alice.near': {
      profile: {
        bio: null, // This deletes the bio key
      },
    },
  },
});
await tx.send();

Delete Multiple Keys​

const tx = await graph.set({
  signerId: 'alice.near',
  data: {
    'alice.near': {
      profile: {
        bio: null,
        tags: null,
      },
    },
  },
});
await tx.send();

Storage Management​

Check Storage Balance​

const balance = await graph.storageBalanceOf('alice.near');
console.log(balance?.available); // Available storage in yoctoNEAR
console.log(balance?.total); // Total storage deposited

Deposit Storage​

const tx = await graph.storageDeposit({
  signerId: 'alice.near',
  deposit: '1000000000000000000000000', // 0.001 NEAR
});
await tx.send();

Withdraw Storage​

const tx = await graph.storageWithdraw({
  signerId: 'alice.near',
  amount: '500000000000000000000000', // Optional: specific amount
});
await tx.send();

Unregister from Storage​

// Note: The current contract implementation prevents unregistration
const tx = await graph.storageUnregister({
  signerId: 'alice.near',
  force: false, // Optional: force unregister even with remaining data
});
await tx.send();

Low-Level Access​

Use Graph for direct contract access:

Read Any Data​

import { Graph } from 'near-social-js';

const graph = new Graph();
const data = await graph.get({
  keys: ['alice.near/profile/**', 'bob.near/widget/*'],
});

Store Custom Data​

const tx = await graph.set({
  signerId: 'alice.near',
  data: {
    'alice.near': {
      myApp: {
        settings: { theme: 'dark', notifications: true },
      },
    },
  },
});
await tx.send();

Query Index​

const posts = await graph.index({
  action: 'post',
  key: 'main',
  order: 'desc',
  limit: 20,
});

Data Patterns​

Key Structure​

Data is stored hierarchically: {accountId}/{category}/{key}

TypePath Example
Profilealice.near/profile/name
Postalice.near/post/main
Commentalice.near/post/comment
Widgetalice.near/widget/MyWidget
Followalice.near/graph/follow/bob.near

Wildcards​

  • * — Match one level
  • ** — Match all nested levels
// Get all profile fields
await graph.get({ keys: ['alice.near/profile/*'] });

// Get entire profile including nested
await graph.get({ keys: ['alice.near/profile/**'] });

// Get all widgets from all accounts
await graph.get({ keys: ['*/widget/*'] });

Index Actions​

ActionDescription
postPosts feed
likeLikes on items
commentComments on posts
repostReposts
graphFollow/unfollow events
notifyNotifications
hashtagHashtag indexing