NIN SDK

Official JavaScript/TypeScript SDK for NIN. Use it to connect your users to supported services, discover available tools, and execute those tools from your server.

Installation

npm install @nin.in/core

pnpm add @nin.in/core

yarn add @nin.in/core

Quick Start

import { Nin } from "@nin.in/core";

const nin = new Nin({
  apiKey: process.env.NIN_API_KEY!,
});

const session = nin.session("user_123");

const plugins = await nin.getPlugins();
console.log(plugins);

Use the SDK from your backend, API routes, server actions, or workers. Do not expose your NIN API key in browser code.

Configuration

By default, the SDK connects to the hosted NIN API:

https://connect.nin.in

For self-hosted NIN servers, set BASE_URL:

BASE_URL=https://your-nin-server.com
NIN_API_KEY=nk_live_xxx

Then initialize the SDK normally:

import { Nin } from "@nin.in/core";

const nin = new Nin({
  apiKey: process.env.NIN_API_KEY!,
});

You can also pass the URL directly:

const nin = new Nin({
  apiKey: process.env.NIN_API_KEY!,
  baseUrl: "https://your-nin-server.com",
});

Explicit baseUrl takes priority over BASE_URL.

Core Concepts

Nin is the main SDK client. It is configured with your developer API key.

Session is scoped to one end user in your application. Create one with nin.session(userId).

Plugin is an integration such as Gmail, Slack, Google Calendar, or another supported service.

Tool is an action that can be executed after the user has connected a plugin.

List Available Plugins

import { Nin } from "@nin.in/core";

const nin = new Nin({
  apiKey: process.env.NIN_API_KEY!,
});

const plugins = await nin.getPlugins();

for (const plugin of plugins) {
  console.log(plugin.slug, plugin.name, plugin.toolCount);
}

You can also check plugin availability for a specific user:

const plugins = await nin.getPlugins({
  userId: "user_123",
});

Create a User Session

const session = nin.session("user_123");

Use a stable ID from your own application, such as your database user ID.

Start an OAuth Connection

Use initiateConnection when the user needs to authorize a service through a redirect flow.

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  redirectUrl: "https://your-app.com/settings/integrations",
});

return Response.redirect(connectUrl);

For MCP-based connection flows:

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  connectionType: "mcp",
  redirectUrl: "https://your-app.com/settings/integrations",
});

Create a Credential-Based Connection

Use createConnection when the plugin supports direct credentials such as an API key or bearer token.

const result = await session.createConnection({
  plugin: "github",
  authMethod: "api_key",
  credentials: {
    apiKey: process.env.GITHUB_TOKEN!,
  },
  accountLabel: "Production GitHub",
});

console.log(result.connected);

List User Connections

const connections = await session.getConnections();

for (const connection of connections) {
  console.log(connection.pluginSlug, connection.accountLabel);
}

Discover Tools

Fetch tools available to the user. You can filter by plugin slug.

const tools = await session.getTools({
  plugins: ["gmail"],
});

for (const tool of tools) {
  console.log(tool.slug, tool.description);
}

Execute a Tool

Once a user has connected a plugin, execute a tool with input parameters.

const result = await session.execute("GMAIL_SEND_EMAIL", {
  to: "[email protected]",
  subject: "Hello from NIN",
  body: "This email was sent through the NIN SDK.",
});

if (!result.success) {
  throw new Error(result.error ?? "Tool execution failed");
}

console.log(result.data);

Disconnect a User

Disconnect by plugin:

await session.disconnectConnection({
  plugin: "gmail",
});

Or disconnect a specific connection:

await session.disconnectConnection({
  connectionId: "conn_123",
});

Complete Example

import { Nin } from "@nin.in/core";

const nin = new Nin({
  apiKey: process.env.NIN_API_KEY!,
});

async function sendWelcomeEmail(userId: string, email: string) {
  const session = nin.session(userId);

  const connections = await session.getConnections();
  const hasGmail = connections.some(
    (connection) => connection.pluginSlug === "gmail"
  );

  if (!hasGmail) {
    const { connectUrl } = await session.initiateConnection({
      plugin: "gmail",
      redirectUrl: "https://your-app.com/settings/integrations",
    });

    return {
      connected: false,
      connectUrl,
    };
  }

  const result = await session.execute("GMAIL_SEND_EMAIL", {
    to: email,
    subject: "Welcome",
    body: "Thanks for connecting your account.",
  });

  return {
    connected: true,
    result,
  };
}

API Reference

new Nin(config)

const nin = new Nin({
  apiKey: "nk_live_xxx",
  baseUrl: "https://your-nin-server.com",
  timeoutMs: 60_000,
});

| Option | Type | Required | Description | | --- | --- | --- | --- | | apiKey | string | Yes | Your NIN API key. | | baseUrl | string | No | Override the API URL. Defaults to BASE_URL, then https://connect.nin.in. | | timeoutMs | number | No | Request timeout in milliseconds. Defaults to 60000. |

nin.getPlugins(options?)

Lists available plugins.

const plugins = await nin.getPlugins();

nin.session(userId)

Creates a user-scoped session.

const session = nin.session("user_123");

session.initiateConnection(options)

Starts an OAuth or redirect-based connection flow.

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  redirectUrl: "https://your-app.com/callback",
});

session.createConnection(options)

Creates a connection using direct credentials.

await session.createConnection({
  plugin: "github",
  authMethod: "api_key",
  credentials: {
    apiKey: "ghp_xxx",
  },
});

session.getConnections()

Lists active connections for the user.

const connections = await session.getConnections();

session.getTools(options?)

Lists tools available to the user.

const tools = await session.getTools({
  plugins: ["gmail"],
});

session.execute(tool, params?)

Executes a tool for the user.

const result = await session.execute("GMAIL_SEND_EMAIL", {
  to: "[email protected]",
});

session.disconnectConnection(options)

Disconnects a plugin or connection.

await session.disconnectConnection({
  plugin: "gmail",
});