@tachles/link

v1.0.5

Published

7 days ago

Universal JavaScript/TypeScript SDK + CLI Tool for Tachles Link

0High
0Medium
0Low

tachles-dev

tachles link telemetry monitoring sdk

@tachles/link

Universal JavaScript/TypeScript SDK and CLI tool for Tachles Link - the intelligent telemetry and monitoring platform.

🚀 Features

Universal SDK: Works with Node.js backends and React frontends
Zero Configuration: Automatic environment variable detection
Resilient: Never crashes your application, even if the Mothership is down
Lightweight: Minimal overhead and dependencies
Type-Safe: Full TypeScript support with type definitions
Easy Setup: CLI tool for quick initialization

📦 Installation

npm install @tachles/link

🔧 Quick Start

1. Initialize the SDK

Run the CLI tool to authenticate and configure your project:

npx link init

Interactive Setup:

Enter your Mothership URL
Enter your Application Name
Paste your User Master Key
Choose auto-activate or manual approval

Two Provisioning Flows:

Auto-Activate (Recommended for development): Instant credentials without dashboard approval
Manual Approval: Requires dashboard confirmation before receiving credentials

The CLI will create a .env file with your credentials automatically.

2. Use in Node.js (Express, NestJS, Workers)

import { Link } from "@tachles/link/node";

// Automatically loads from .env and initializes!
const link = new Link();

// Track custom events - works immediately
await link.track("user_signup", { userId: "123", plan: "pro" });

// Capture exceptions
try {
  // your code
} catch (error) {
  await link.captureException(error);
}

3. Use in React (Next.js, Vite, SPA)

Next.js App Router (app/layout.tsx):

import { TachlesLink } from "@tachles/link/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <TachlesLink 
          host={process.env.NEXT_PUBLIC_LINK_HOST}
          appId={process.env.NEXT_PUBLIC_LINK_APP_ID}
          debug={false}
        />
      </body>
    </html>
  );
}

Vite/CRA:

import { TachlesLink } from "@tachles/link/react";

function App() {
  return (
    <>
      <YourApp />
      <TachlesLink 
        host={import.meta.env.VITE_LINK_HOST}
        appId={import.meta.env.VITE_LINK_APP_ID}
      />
    </>
  );
}

Manual Tracking Hook

import { useTachlesLink } from "@tachles/link/react";

function MyComponent() {
  const { track } = useTachlesLink(
    process.env.NEXT_PUBLIC_LINK_HOST,
    process.env.NEXT_PUBLIC_LINK_APP_ID
  );

  const handleClick = () => {
    track("button_clicked", { buttonId: "cta-main" });
  };

  return <button onClick={handleClick}>Click Me</button>;
}

🔑 Environment Variables

After running npx link init, these variables are added to your .env:

LINK_HOST=https://link.tachles.dev
LINK_APP_ID=x-link-id-value
LINK_APP_SECRET=lk_app_secret_value

For React/Frontend:

Prefix with NEXT_PUBLIC_ (Next.js) or VITE_ (Vite) to make them available client-side:

NEXT_PUBLIC_LINK_HOST=https://link.tachles.dev
NEXT_PUBLIC_LINK_APP_ID=x-link-id-value

Security Note: Never expose LINK_APP_SECRET to the client. React SDK only needs host and appId.

📖 API Reference

Node.js Runtime

`Link` Class

Constructor:

new Link(config?: Partial<LinkConfig>, debug?: boolean)

Methods:

start(): Initialize telemetry, send boot event, start heartbeat
track(event: string, payload?: object): Track custom events
captureException(error: Error): Send error to Mothership

Configuration:

interface LinkConfig {
  host?: string;
  appId?: string;
  appSecret?: string;
}

React Runtime

`<TachlesLink />` Component

Props:

interface TachlesLinkProps {
  host?: string;
  appId?: string;
  debug?: boolean;
}

`useTachlesLink()` Hook

const { track } = useTachlesLink(host, appId);
track(event: string, payload?: object);

🔒 Security

Node.js: Uses LINK_APP_SECRET for authenticated requests
React: Only uses LINK_APP_ID (public identifier)
All network requests are wrapped in error handlers
SDK never crashes your application

🛠️ Development

Build

npm run build

Type Checking

npm run typecheck

Watch Mode

npm run dev

📂 Package Structure

@tachles/link
├── /node          # Node.js runtime
├── /react         # React runtime  
└── CLI (npx link) # Initialization tool

Exports:

@tachles/link/node - Server-side SDK
@tachles/link/react - Client-side React component

🧪 Testing

The SDK is designed to be resilient:

All API calls are wrapped in try/catch
Failed requests log warnings but don't throw
Heartbeat continues even if individual requests fail

📄 License

MIT

🤝 Support

🎯 Telemetry Events

Automatic (Node.js)

boot: Sent on startup
heartbeat: Sent every 60s with system metrics
shutdown: Sent on graceful exit

Automatic (React)

page_view: Sent on component mount
session_end: Sent on visibility change
page_unload: Sent before page unload

Manual

custom: Track any event via track() or useTachlesLink().track()
error: Capture exceptions via captureException()

Made with ❤️ by Tachles

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tachles/link

🚀 Features

📦 Installation

🔧 Quick Start

1. Initialize the SDK

2. Use in Node.js (Express, NestJS, Workers)

3. Use in React (Next.js, Vite, SPA)

Manual Tracking Hook

🔑 Environment Variables

For React/Frontend:

📖 API Reference

Node.js Runtime

Link Class

React Runtime

<TachlesLink /> Component

useTachlesLink() Hook

🔒 Security

🛠️ Development

Build

Type Checking

Watch Mode

📂 Package Structure

🧪 Testing

📄 License

🤝 Support

🎯 Telemetry Events

Automatic (Node.js)

Automatic (React)

Manual

`Link` Class

`<TachlesLink />` Component

`useTachlesLink()` Hook