SDK API Reference
Complete TypeScript API reference for the @nin.in/core SDK.
Nin
Top-level SDK entry point. Created once per application.
Constructor
new Nin(config: NinConfig)| Property | Type | Default | Description |
|---|---|---|---|
apiKey | string | — | Required. Your developer API key from the dashboard |
baseUrl | string | "https://connect.nin.in" | Override for self-hosted or local dev |
timeoutMs | number | 60000 | Request timeout in milliseconds |
Methods
nin.session(userId: string): Session
Create a user-scoped session. All operations within the session include the user ID automatically.
nin.getPlugins(opts?: GetPluginsOpts): Promise<Plugin[]>
List all available plugins on the platform.
| Option | Type | Description |
|---|---|---|
userId | string | If provided, includes connected status for this user |
Session
User-scoped client. Created via nin.session("user_id").
Methods
session.getTools(opts?: GetToolsOpts): Promise<ToolDefinition[]>
Get tool definitions, optionally filtered by plugin. The SDK automatically passes the session's userId to enable realtime MCP tool discovery — if a plugin has MCP configured and the user has an MCP connection, tools are fetched live from the MCP server.
| Option | Type | Description |
|---|---|---|
plugins | string[] | Filter by plugin slugs (e.g. ["gmail", "stripe"]) |
session.getConnections(): Promise<Connection[]>
List the user's active connections.
session.initiateConnection(opts: InitiateConnectionOpts): Promise<{ connectUrl: string; redirectUrl: string }>
Generate a connect URL for the end-user. Returns either an OAuth authorization URL (if authMethod is "oauth2") or a hosted connect page URL showing available auth methods. The response also echoes the resolved redirectUrl encoded into the OAuth state.
| Option | Type | Description |
|---|---|---|
plugin | string | Required. Plugin slug |
authMethod | string | If omitted, the hosted connect page shows all available auth methods. If "oauth2", returns the provider's authorization URL directly. If another type (e.g. "api_key"), the hosted page is filtered to that method only. |
connectionType | string | "rest" (default) or "mcp". When "mcp", initiates an OAuth flow with PKCE targeting the plugin's MCP server. |
redirectUrl | string | Required. URL to redirect the user back to after connecting |
session.createConnection(opts: CreateConnectionOpts): Promise<{ connected: boolean }>
Directly submit credentials for a connection.
| Option | Type | Description |
|---|---|---|
plugin | string | Required. Plugin slug |
authMethod | string | Required. Auth method type (e.g. "api_key_header") |
credentials | Record<string, string> | Required. Key-value pairs of credentials |
accountLabel | string | Optional display label for the connection |
session.disconnectConnection(opts: DisconnectConnectionOpts): Promise<{ disconnected: boolean }>
Remove this user's saved connection. Pass either a plugin slug or a connection ID returned by getConnections().
| Option | Type | Description |
|---|---|---|
plugin | string | Plugin slug to disconnect, e.g. "gmail" |
connectionId | string | Specific connection ID returned by getConnections() |
session.execute(tool: string, params?: Record<string, unknown>): Promise<ToolResult>
Execute a tool with automatic auth injection.
| Parameter | Type | Description |
|---|---|---|
tool | string | Required. Tool slug (e.g. "GMAIL_SEND_EMAIL") |
params | Record<string, unknown> | Tool-specific parameters matching the input schema |
Types
Plugin
interface Plugin {
id: string;
slug: string;
name: string;
description: string | null;
iconUrl: string | null;
pluginPrompt: string | null;
status: string;
categories?: Array<{ id: string; slug: string; name: string }>;
authMethods: Array<{ type: string; label: string; isDefault: boolean }>;
toolCount: number;
connected?: boolean;
}ToolDefinition
interface ToolDefinition {
id: string;
slug: string;
name: string;
description: string;
method?: string; // present for manual tools, absent for MCP tools
path?: string; // present for manual tools, absent for MCP tools
inputSchema: Record<string, unknown> | null;
outputSchema: Record<string, unknown> | null;
pluginSlug: string;
pluginName: string;
source?: "manual" | "mcp"; // indicates where the tool was discovered from
}Connection
interface Connection {
id: string;
pluginSlug: string;
pluginName: string;
authMethodType: string | null; // null for MCP-only connections
accountLabel: string | null;
hasMcpTokens: boolean; // true if MCP access token is stored
createdAt: string;
}DisconnectConnectionOpts
type DisconnectConnectionOpts =
| { plugin: string; connectionId?: never }
| { connectionId: string; plugin?: never };ToolResult
interface ToolResult {
success: boolean;
data?: unknown;
error?: string;
status?: number;
latencyMs: number;
}