npm package: @linkage-open/lib
Description: The official SDK for building applications on Linkage.
Latest version: 0.1.0

# @linkage-open/lib

The official SDK for building applications on Linkage.

## Features

- 🎨 **Flexible UI Components** - Pre-built React components for workflows and nodes
- 🔄 **Real-Time Collaboration** - Built-in Liveblocks integration for collaborative features
- 🎯 **Type-Safe** - Full TypeScript support
- ⚡ **Optimized** - Performance-focused architecture
- 🔐 **Secure** - Built-in authentication and authorization
- 📊 **Editor Component** - All-in-one collaborative workflow editor with @xyflow/react

## Installation

```bash
npm install @linkage-open/lib
```

### Peer Dependencies

```bash
npm install react react-dom
```

For real-time collaboration:
```bash
npm install @liveblocks/client @liveblocks/react
```

For workflow editor:
```bash
npm install @xyflow/react
```

## Quick Start

### Define a Node Registry

```ts
import { defineNode, defineNodeRegistry } from "@linkage-open/lib";
import { z } from "zod";

export const registry = defineNodeRegistry({
  version: "1.0.0",
  nodes: [
    defineNode({
      name: "Example Node",
      type: "example",
      input: {
        customerId: {
          schema: z.string(),
          reduce: false,
          userInput: true,
        },
      },
      output: {
        greeting: {
          schema: z.string(),
          reduce: false,
        },
      },
    }),
  ],
});
```

### Basic Workflow Editor

```tsx
import { Editor, ClientProvider } from "@linkage-open/lib/react";

function App() {
  return (
    <ClientProvider
      config={{
        clientAppId: "your-app-id",
        clientAppSecret: "your-secret",
        workflowId: "workflow_123",
        userId: "user_123",
      }}
    >
      <Editor nodeTypes={customNodeTypes} />
    </ClientProvider>
  );
}
```

### Collaborative Workflow Editor

```tsx
import { Editor, ClientProvider } from "@linkage-open/lib/react";

function App() {
  return (
    <ClientProvider
      config={{
        clientAppId: "your-app-id",
        clientAppSecret: "your-secret",
        workflowId: "workflow_123",
        userId: "user_123",
      }}
      liveblocks={{
        enabled: true,
        roomId: "my-workflow-room",
        publicKey: process.env.NEXT_PUBLIC_LIVEBLOCKS_KEY
      }}
    >
      <Editor
        nodeTypes={customNodeTypes}
        enableCollaboration
        roomId="my-workflow-room"
        liveblocks={{
          publicKey: process.env.NEXT_PUBLIC_LIVEBLOCKS_KEY
        }}
      />
    </ClientProvider>
  );
}
```

## Real-Time Collaboration

Linkage provides out-of-the-box real-time collaboration powered by Liveblocks. See the [Liveblocks Integration Guide](./LIVEBLOCKS.md) for details.

### Quick Example

```tsx
import { createLiveblocksContext, Cursor } from "@linkage-open/lib/react";

const { RoomProvider, useMyPresence, useOthers } =
  createLiveblocksContext({
    publicKey: "pk_prod_r4T9Q4ZxehLDLoQOjlEBWBcJKLocfU2f2tVsjbabbCaefeHPBkC_m2_cYZubNiOx",
  });

function CollaborativeApp() {
  return (
    <RoomProvider id="my-room" initialPresence={{ cursor: null }}>
      <Canvas />
    </RoomProvider>
  );
}
```

## Components

### Editor

All-in-one workflow editor component with optional real-time collaboration.

**Props:**
- `nodeTypes` - Custom ReactFlow node types
- `enableCollaboration` - Enable real-time collaboration features
- `roomId` - Liveblocks room ID (required if collaboration is enabled)
- `liveblocks` - Liveblocks configuration (publicKey or authEndpoint)

### ClientProvider

Root provider component with optional Liveblocks integration.

**Props:**
- `config` - Client configuration (clientAppId, clientAppSecret, workflowId, userId)
- `liveblocks` - Optional Liveblocks configuration for automatic room setup

## Documentation

- [Liveblocks Integration](./LIVEBLOCKS.md) - Complete guide for real-time collaboration
- [Examples](./examples/) - Working examples and demos
- [API Reference](https://linkage.dev/docs)

## Examples

Check out the [examples directory](./examples/) for complete working examples:

- **Collaborative Cursor Tracking** - Simple real-time cursor tracking
- **Secure Collaboration** - Production-ready with authentication

## License

MIT