npm package: @plural_pinelabs/agent-toolkit
Description: Pinelabs Agent Toolkit — integrate Pine Labs payment APIs with AI agent frameworks (OpenAI, LangChain, Vercel AI SDK)
Author: Pine Labs
Latest version: 0.1.5

# Pine Labs Agent Toolkit

Build AI-powered payment agents with LangChain, Vercel AI SDK, and OpenAI Agents SDK.

The Pine Labs Agent Toolkit enables popular agent frameworks — LangChain, Vercel's AI SDK, and OpenAI's Agents SDK — to integrate with Pine Labs payment APIs through function calling. Build AI-powered payment agents that can create orders, process payments, and manage transactions programmatically.

---

## Pre-requisites

- Create a Pine Labs merchant account and obtain your **Client ID** and **Client Secret** from the [Pine Labs Developer Dashboard](https://developer.pinelabsonline.com).
- Node.js **v18 or later**.

---

## Installation

```bash
# npm
npm install @plural_pinelabs/agent-toolkit

# yarn
yarn add @plural_pinelabs/agent-toolkit

# pnpm
pnpm add @plural_pinelabs/agent-toolkit
```

---

## Framework Support

| Framework     | Import Path                               | Description                             |
| ------------- | ----------------------------------------- | --------------------------------------- |
| OpenAI        | `@plural_pinelabs/agent-toolkit/openai`    | For Chat Completions API and Agents SDK |
| LangChain     | `@plural_pinelabs/agent-toolkit/langchain` | For LangChain agents                    |
| Vercel AI SDK | `@plural_pinelabs/agent-toolkit/ai-sdk`    | For Vercel's AI SDK                     |

---

## Available Tools

| Tool            | Description                                               | Status       |
| --------------- | --------------------------------------------------------- | ------------ |
| `createOrder`   | Create a new payment order                                | ✅ Available  |
| `getOrder`      | Retrieve details of an existing order by order ID         | ✅ Available  |
| `cancelOrder`   | Cancel or terminate an order                              | ✅ Available  |
| `createRefund`  | Initiate a refund for an order                            | ✅ Available  |

---

## OpenAI

The OpenAI integration supports both the **Chat Completions API** and the **Agents SDK**.

### With OpenAI Agents SDK

```typescript
import { Agent, run } from '@openai/agents';
import {
  PinelabsAgentToolkit,
  pinelabsEnvironment,
} from '@plural_pinelabs/agent-toolkit/openai';

const pinelabs = new PinelabsAgentToolkit(
  pinelabsEnvironment.UAT,               // or pinelabsEnvironment.PRODUCTION
  process.env.PINE_CLIENT_ID!,
  process.env.PINE_CLIENT_SECRET!
);

const agent = new Agent({
  name: 'Payment Agent',
  instructions: 'You are a helpful payment assistant.',
  model: 'gpt-4o',
  tools: pinelabs.getAgentTools(),
});

const result = await run(agent, 'Create an order for Rs. 500 for customer john@example.com');
console.log(result.finalOutput);
```

### With Chat Completions API

```typescript
import OpenAI from 'openai';
import {
  PinelabsAgentToolkit,
  pinelabsEnvironment,
} from '@plural_pinelabs/agent-toolkit/openai';

const openai = new OpenAI();

const pinelabs = new PinelabsAgentToolkit(
  pinelabsEnvironment.UAT,
  process.env.PINE_CLIENT_ID!,
  process.env.PINE_CLIENT_SECRET!
);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Create an order for Rs. 500' }],
  tools: pinelabs.getTools(),
});

for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await pinelabs.handleToolCall(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
  console.log(result);
}
```

---

## LangChain

```typescript
import { ChatOpenAI } from '@langchain/openai';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatPromptTemplate } from '@langchain/core/prompts';
import {
  PinelabsAgentToolkit,
  pinelabsEnvironment,
} from '@plural_pinelabs/agent-toolkit/langchain';

const pinelabs = new PinelabsAgentToolkit(
  pinelabsEnvironment.UAT,
  process.env.PINE_CLIENT_ID!,
  process.env.PINE_CLIENT_SECRET!
);

const tools = pinelabs.getTools(); // DynamicStructuredTool[]

const llm = new ChatOpenAI({ model: 'gpt-4o' });
const prompt = ChatPromptTemplate.fromMessages([
  ['system', 'You are a helpful payment assistant.'],
  ['human', '{input}'],
  ['placeholder', '{agent_scratchpad}'],
]);

const agent = await createOpenAIFunctionsAgent({ llm, tools, prompt });
const executor = new AgentExecutor({ agent, tools });

const result = await executor.invoke({ input: 'Create an order for Rs. 500' });
console.log(result.output);
```

---

## Vercel AI SDK

```typescript
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import {
  PinelabsAgentToolkit,
  pinelabsEnvironment,
} from '@plural_pinelabs/agent-toolkit/ai-sdk';

const pinelabs = new PinelabsAgentToolkit(
  pinelabsEnvironment.UAT,
  process.env.PINE_CLIENT_ID!,
  process.env.PINE_CLIENT_SECRET!
);

const result = await generateText({
  model: openai('gpt-4o'),
  tools: pinelabs.getTools(),
  prompt: 'Create an order for Rs. 500',
  maxSteps: 5,
});

console.log(result.text);
```

---

## Environment Variables

| Variable             | Description                                      |
| -------------------- | ------------------------------------------------ |
| `PINE_CLIENT_ID`     | Client ID from the Pine Labs Developer Dashboard |
| `PINE_CLIENT_SECRET` | Client Secret from the Pine Labs Developer Dashboard |

## Environments

| Environment | Constant                         | Base URL                           |
| ----------- | -------------------------------- | ---------------------------------- |
| UAT         | `pinelabsEnvironment.UAT`        | `https://pluraluat.v2.pinepg.in`   |
| Production  | `pinelabsEnvironment.PRODUCTION` | `https://api.pluralpay.in`         |

---

## Authentication

All tools authenticate automatically using the `client_id` and `client_secret` passed to the toolkit constructor. Tokens are cached and refreshed before expiry with no manual management required.

For `createOrder`, the agent supplies the merchant `client_id` and `client_secret` directly as tool parameters alongside the order details. The SDK obtains a Bearer token internally and calls the checkout API in a single step.

---

## Resources

- [Pine Labs Developer Documentation](https://developer.pinelabsonline.com/reference)
- [npm Package](https://www.npmjs.com/package/@plural_pinelabs/agent-toolkit)
- [GitHub Repository](https://github.com/pinelabsonline/agent-toolkit)

---

## License

MIT