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

const tx = await social.createPost('alice.near', {
  text: 'Hello NEAR! 🚀',
});
await tx.send();

Get a Post

const post = await social.getPost('alice.near', 123456789);
console.log(post?.text); // "Hello NEAR! 🚀"

Social Graph

Follow an Account

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

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');
// { "dave.near": "", "eve.near": "" }

Likes

Like a Post

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

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

Get Likes

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

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}

Type	Path Example
Profile	alice.near/profile/name
Post	alice.near/post/main
Widget	alice.near/widget/MyWidget
Follow	alice.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

Action	Description
post	Posts feed
like	Likes on items
comment	Comments on posts
graph	Follow/unfollow events
notify	Notifications