Lyrra SDK

Lyrra is a lightweight client library for sending usage‑tracking events to the Lyrra monitoring service. The npm package provides adapters for supported environments; all proprietary logic runs on the service side.

NOTE Keep your LYRRA_API_KEY secret – never bake it into client code.

Installation

npm install lyrra-sdk
# or pnpm add lyrra-sdk

Quick start

1. Set the following environment variables on the server where you send events:

   LYRRA_APP_KEY=your-app-key
   LYRRA_API_KEY=your-secret-token

2. Install the package and use one of the adapters shown below; the client code handles buffering and delivery automatically. A hybrid buffer is used by default: events are flushed either when 20 items accumulate or every 15 seconds, whichever comes first, reducing variability in send intervals.

Next.js (App Router)

1. Add lyrra-sdk to transpilePackages in next.config.js so the library's "use client"/"use server" directives are preserved:

   // next.config.js
   module.exports = {
     experimental: { serverActions: true },
     transpilePackages: ["lyrra-sdk"],
   };

2. Wrap your root layout with LyrraProvider (client entrypoint):

   "use client";
   import { LyrraProvider } from "lyrra-sdk/next/client";
   
   export default function RootLayout({ children }) {
     return <LyrraProvider>{children}</LyrraProvider>;
   }

   The provider tracks page‑views automatically. Use useLyrra() from the same client path for manual events:

   import { useLyrra } from "lyrra-sdk/next/client";
   
   export default function CheckoutButton() {
     const { track } = useLyrra();
     return <button onClick={() => track("checkout.clicked")}>Checkout</button>;
   }

3. Recording events from server code

   • Server actions / other server helpers

     import { lyrraAction } from "lyrra-sdk/next/actions";
     
     export async function someAction() {
       await lyrraAction({ events: [{ event: "order.completed" }] });
     }

   • API route

     // app/api/lyrra/route.ts
     import { createLyrraHandler } from "lyrra-sdk/next"; // server entrypoint
     export const POST = createLyrraHandler();

     The older internalServerTrack export is treated as a private symbol and may be renamed; prefer the helpers above.

Express

import express from "express";
import { lyrraMiddleware } from "lyrra-sdk/express";

const app = express();
app.use(
  lyrraMiddleware({
    appKey: process.env.LYRRA_APP_KEY!,
    apiKey: process.env.LYRRA_API_KEY!,
  }),
);

The middleware emits a page‑view on every request. Custom events can be sent using the standalone track helper from the root package:

import { track } from "lyrra-sdk";

await track({ event: "order.completed", properties: { orderId: 123 } });

⚠️ Avoid writing loops or floods of events with the same token; the service applies per‑token rate limiting and may temporarily block abusive clients.

Payload format

Events are JSON objects with the following shape. Timestamps are added server‑side; clients should omit them.

{
  "event": "string",
  "properties": { "key": "value" }
}

Values may be strings, numbers, arrays, objects, etc.

Privacy

• The SDK transmits whatever you supply and retains nothing.
• Never include personal identifiers (email, IP, name, user ID, etc.) — hashing or anonymizing them is not permitted.
• Any association of events to users must be done outside the SDK.

For more configuration options, advanced usage, and technical details such as buffering behaviour, relay settings, or obfuscation, visit the full documentation at:

https://lyrra.net/docs

License

This SDK is proprietary software. See LICENSE for terms.