SDK Overview

Install and use the @nin.in/core TypeScript SDK to integrate NIN Connect into your application.

Installation

npm install @nin.in/core

Quick Start

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

// initialize with your API key from the dashboard
const nin = new Nin({ apiKey: "nk_live_..." });

// create a user-scoped session
const session = nin.session("user_123");

// list available plugins
const plugins = await nin.getPlugins();

// get tools for a specific plugin
const tools = await session.getTools({ plugins: ["gmail"] });

// execute a tool — auth is injected automatically
const result = await session.execute("GMAIL_SEND_EMAIL", {
  to: "hello@example.com",
  subject: "Hello from NIN",
  body: "This email was sent by an AI agent.",
});

Core Concepts

Nin (Top-Level Client)

The entry point. Created once with your API key. Handles platform-level operations like listing plugins.

const nin = new Nin({
  apiKey: "nk_live_...",         // required
  baseUrl: "http://localhost:3100", // optional, for self-hosted
  timeoutMs: 30_000,            // optional, default 60s
});

Session (User-Scoped)

All user-facing operations happen through a session. A session is scoped to a single end-user ID — your app's user identifier.

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

Through a session you can:

Get tools — list available tool definitions
Get connections — see the user's active connections
Initiate connection — start an OAuth flow or open a connect page
Create connection — directly submit credentials (API key, bearer token)
Disconnect connection — remove a user's saved plugin credentials
Execute tools — run a tool with automatic auth injection

Connecting Users

Before a user can execute tools, they need a connection to the plugin. The easiest way is the hosted connect URL — NIN shows the right UI and handles everything.

Hosted connect URL (recommended):

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  redirectUrl: "https://your-app.com/callback",
});
// redirect or link the user to connectUrl
// NIN shows all available auth methods (OAuth, API key, etc.)
// user completes the flow → redirected back to your redirectUrl

When authMethod is omitted, the hosted page shows all available auth methods for the plugin. Pass a specific authMethod to narrow it to one:

const { connectUrl } = await session.initiateConnection({
  plugin: "gmail",
  authMethod: "oauth2", // goes straight to Google OAuth
  redirectUrl: "https://your-app.com/callback",
});

Direct credentials (server-side):

If you already have the credentials (e.g. the user entered an API key in your own UI), skip the hosted page:

await session.createConnection({
  plugin: "openai",
  authMethod: "api_key",
  credentials: { api_key: "sk-..." },
});

Disconnect:

Remove a saved connection when the user turns off an integration:

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

Next Steps

API Reference — all methods, parameters, and types
Providers — framework-specific guides (Vercel AI SDK, OpenAI Agents, Claude)