@birdie-so/snippet 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# @birdie-so/snippet
+
+Easily integrate the Birdie screen recording snippet into your application using modern frameworks like **React**, **Vue**, **Angular**, or plain **JavaScript** — with full control over initialization, metadata, and event hooks.
+
+> ⚡ This package is a helper utility for integrating Birdie.  
+> **You must have a Birdie account and a valid `clientId` to use this package.**  
+> It does **not work on its own** — visit [https://app.birdie.so](https://app.birdie.so) to get started.
+
+> ⚡ The core logic is still loaded from our CDN. This package is just a light wrapper for easier integration and customization.
+
+![npm](https://img.shields.io/npm/v/@birdie-so/snippet?label=npm%20version)
+![license](https://img.shields.io/npm/l/@birdie-so/snippet)
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install @birdie-so/snippet
+# or
+yarn add @birdie-so/snippet
+```
+
+---
+
+## ✨ Quick Start
+
+### React / Vue / Angular / JS
+
+```js
+import { initBirdie } from "@birdie-so/snippet";
+
+initBirdie({
+  clientId: "YOUR_CLIENT_ID", // required
+
+  // Optional metadata available to recordings
+  metadata: {
+    user: {
+      id: "123",
+      email: "user@example.com",
+    },
+  },
+
+  // Optional hook once Birdie is ready
+  onReady(birdie) {
+    birdie.on("start", (data) => {
+      console.log("Recording started", data);
+      birdie.metadata = { dynamicKey: "value" };
+    });
+
+    birdie.on("stop", (data) => {
+      console.log("Recording stopped", data);
+    });
+  },
+});
+```
+
+---
+
+## 🧠 How It Works
+
+This package:
+
+- Injects the Birdie CDN snippet dynamically using your `clientId`.
+- Sets global `window.birdieSettings` before loading.
+- Registers event callbacks once the Birdie SDK is ready (`window.birdie` is available).
+
+Your original snippet like this:
+
+```html
+<script>
+  window.birdieSettings = {
+    /* ... */
+  };
+</script>
+<script src="https://app.birdie.so/widget/embed/YOUR_CLIENT_ID"></script>
+```
+
+Is now handled via code with `initBirdie()`.
+
+---
+
+## 🧩 Advanced
+
+### Get Birdie instance later
+
+```js
+import { getBirdieInstance } from "birdie-snippet";
+
+getBirdieInstance((birdie) => {
+  birdie.on("start", () => {
+    console.log("Recording started!");
+  });
+});
+```
+
+Or synchronously:
+
+```js
+const birdie = getBirdieInstance();
+if (birdie) {
+  birdie.metadata = { key: "value" };
+}
+```
+
+---
+
+## 📘 Docs
+
+For full documentation and integration examples, visit [our docs page](https://docs.birdie.so/birdie-docs/request-screen-recordings/installation/snippet)
+
+---
+
+## 🛠 Support
+
+Need help? Reach out to us at [support@birdie.so](mailto:support@birdie.so)
+
+---
+
+## 📄 License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "@birdie-so/snippet",
+    "version": "1.0.0",
+    "description": "Helper for integrating the Birdie screen recording snippet into modern JavaScript apps. Requires a Birdie account.",
+    "main": "src/index.js",
+    "exports": {
+        ".": {
+            "require": "./src/index.js",
+            "import": "./src/index.js"
+        }
+    },
+    "types": "src/index.d.ts",
+    "keywords": [
+        "birdie",
+        "screen-recording",
+        "console-logs",
+        "network-logs",
+        "debug",
+        "snippet",
+        "frontend",
+        "support"
+    ],
+    "license": "MIT",
+    "author": "Birdie <support@birdie.so>",
+    "publishConfig": {
+        "access": "public"
+    },
+    "homepage": "https://docs.birdie.so",
+    "files": [
+        "src/",
+        "README.md"
+    ]
+}

package/src/index.d.ts

@@ -0,0 +1,37 @@
+export interface BirdieMetadata {
+    [key: string]: any;
+}
+
+export interface BirdieSettings {
+    /**
+     * Unique Birdie client ID.
+     */
+    clientId: string;
+
+    /**
+     * Optional metadata to pass to Birdie before recording starts.
+     */
+    metadata?: BirdieMetadata;
+
+    /**
+     * Callback when Birdie is fully loaded and available as `window.birdie`.
+     */
+    onReady?: (birdie: BirdieAPI) => void;
+}
+
+export interface BirdieAPI {
+    metadata: BirdieMetadata;
+    on(event: 'start' | 'stop', callback: (data: any) => void): void;
+}
+
+/**
+ * Initializes the Birdie widget by injecting the CDN script with your client ID.
+ * Automatically configures window.birdieSettings and registers optional metadata or event listeners.
+ */
+export function initBirdie(settings: BirdieSettings): void;
+
+/**
+ * Returns the current `window.birdie` instance if available, or null.
+ * You can also pass a callback to run once Birdie becomes available.
+ */
+export function getBirdieInstance(callback?: (birdie: BirdieAPI) => void): BirdieAPI | null;

package/src/index.js

@@ -0,0 +1,57 @@
+let _readyCallbacks = [];
+
+export function initBirdie({ clientId, metadata, onReady, ...otherSettings }) {
+    if (!clientId) {
+        console.error('[Birdie] Missing required clientId in initBirdie()');
+        return;
+    }
+
+    if (typeof window === 'undefined') return;
+
+    // Always predefine birdieSettings first (or reuse if already present)
+    if (!window.birdieSettings) {
+        window.birdieSettings = {};
+    }
+
+    // Assign metadata and other settings first
+    window.birdieSettings.metadata = metadata;
+    Object.assign(window.birdieSettings, otherSettings);
+
+    // Assign onBirdieReady BEFORE appending the script
+    window.birdieSettings.onBirdieReady = () => {
+        _readyCallbacks.forEach(cb => cb(window.birdie));
+        _readyCallbacks = [];
+    };
+
+    // Queue the onReady handler
+    if (onReady) {
+        registerBirdieReadyCallback(onReady);
+    }
+
+    // Inject script if not already
+    if (!document.getElementById('birdie-snippet')) {
+        const script = document.createElement('script');
+        script.src = `https://app.birdie.so/widget/embed/${clientId}`;
+        script.async = true;
+        script.id = 'birdie-snippet';
+        document.body.appendChild(script);
+    }
+}
+
+function registerBirdieReadyCallback(callback) {
+    if (window.birdie) {
+        callback(window.birdie);
+    } else {
+        _readyCallbacks.push(callback);
+    }
+}
+
+export function getBirdieInstance(onReady) {
+    if (window.birdie) {
+        onReady?.(window.birdie);
+        return window.birdie;
+    } else {
+        registerBirdieReadyCallback(onReady);
+        return null;
+    }
+}