@raindrop-ai/wizard 0.0.1

package/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) 2025 PostHog
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Portions of this software are derived from Sentry’s codebase located at https://github.com/getsentry/sentry-wizard and are used under the terms of the MIT License provided below:
+
+The MIT License (MIT)
+
+Copyright (c) 2017 Sentry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { satisfies } from 'semver';
+import { red } from './src/utils/logging.js';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+const NODE_VERSION_RANGE = '>=18.17.0';
+// Node version check - must use console.log before Ink is initialized
+if (!satisfies(process.version, NODE_VERSION_RANGE)) {
+    red(`Raindrop wizard requires Node.js ${NODE_VERSION_RANGE}. You are using Node.js ${process.version}. Please upgrade your Node.js version.`);
+    process.exit(1);
+}
+import { runWizard } from './src/run.js';
+import { isNonInteractiveEnvironment } from './src/utils/environment.js';
+import ui, { initWizardUI } from './src/utils/ui.js';
+// Prevent unhandled rejection errors from showing during graceful shutdown
+process.on('unhandledRejection', (reason) => {
+    // Ignore ProcessTransport errors during shutdown
+    if (reason?.message?.includes('ProcessTransport is not ready') ||
+        reason?.message?.includes('Stream can only be iterated once')) {
+        return;
+    }
+    // Log other unhandled rejections
+    console.error('Unhandled rejection:', reason);
+    process.exit(1);
+});
+// Prevent uncaught exceptions from showing during graceful shutdown
+process.on('uncaughtException', (error) => {
+    // Ignore ProcessTransport errors during shutdown
+    if (error.message?.includes('ProcessTransport is not ready') ||
+        error.message?.includes('Stream can only be iterated once')) {
+        return;
+    }
+    // Log other uncaught exceptions
+    console.error('Uncaught exception:', error);
+    process.exit(1);
+});
+yargs(hideBin(process.argv))
+    .env('RAINDROP')
+    // global options
+    .options({
+    debug: {
+        default: false,
+        describe: 'Enable verbose logging\nenv: RAINDROP_DEBUG',
+        type: 'boolean',
+    },
+    default: {
+        default: false,
+        describe: 'Use default options for all prompts\nenv: RAINDROP_DEFAULT',
+        type: 'boolean',
+    },
+})
+    .command(['$0'], 'Run the Raindrop setup wizard', (yargs) => {
+    return yargs.options({
+        'force-install': {
+            default: false,
+            describe: 'Force install packages even if peer dependency checks fail\nenv: RAINDROP_FORCE_INSTALL',
+            type: 'boolean',
+        },
+        'install-dir': {
+            describe: 'Directory to install Raindrop in\nenv: RAINDROP_INSTALL_DIR',
+            type: 'string',
+        },
+    });
+}, (argv) => {
+    const options = { ...argv };
+    // TTY check - must use console before Ink is initialized
+    if (isNonInteractiveEnvironment()) {
+        red('Raindrop wizard requires an interactive terminal (TTY) to run.\n' +
+            'It appears you are running in a non-interactive environment.\n' +
+            'Please run the Raindrop wizard in an interactive terminal.');
+        process.exit(1);
+    }
+    // Run the async wizard logic
+    void (async () => {
+        // Initialize the unified Ink app (single render call)
+        const wizardUI = await initWizardUI();
+        // Handle Ctrl+C gracefully - exit without showing SDK cleanup errors
+        let sigintCount = 0;
+        const handleSIGINT = () => {
+            sigintCount++;
+            if (sigintCount === 1) {
+                // First Ctrl+C - let the agent handle it gracefully
+                // The agent-interface.ts will handle the interrupt
+                return;
+            }
+            // Second Ctrl+C - force exit immediately
+            wizardUI.unmount();
+            process.exit(130); // Standard exit code for SIGINT
+        };
+        process.on('SIGINT', handleSIGINT);
+        // Display logo through Ink
+        ui.addItem({ type: 'logo', text: '' });
+        try {
+            await runWizard(options);
+            wizardUI.unmount();
+            process.removeListener('SIGINT', handleSIGINT);
+            process.exit(0);
+        }
+        catch (error) {
+            ui.addItem({
+                type: 'error',
+                text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            wizardUI.unmount();
+            process.exit(1);
+        }
+        // The wizard completes - unmount the UI
+        // (cleanup is handled in the try/catch above)
+    })();
+})
+    .help()
+    .alias('help', 'h')
+    .version()
+    .alias('version', 'v')
+    .wrap(null) // null = use terminal width automatically
+    .parse();
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../bin.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { satisfies } from 'semver';\nimport { red } from './src/utils/logging.js';\n\nimport yargs from 'yargs';\nimport { hideBin } from 'yargs/helpers';\n\nconst NODE_VERSION_RANGE = '>=18.17.0';\n\n// Node version check - must use console.log before Ink is initialized\nif (!satisfies(process.version, NODE_VERSION_RANGE)) {\n  red(\n    `Raindrop wizard requires Node.js ${NODE_VERSION_RANGE}. You are using Node.js ${process.version}. Please upgrade your Node.js version.`,\n  );\n  process.exit(1);\n}\n\nimport type { WizardOptions } from './src/utils/types.js';\nimport { runWizard } from './src/run.js';\nimport { isNonInteractiveEnvironment } from './src/utils/environment.js';\nimport ui, { initWizardUI } from './src/utils/ui.js';\n\n// Prevent unhandled rejection errors from showing during graceful shutdown\nprocess.on('unhandledRejection', (reason: any) => {\n  // Ignore ProcessTransport errors during shutdown\n  if (\n    reason?.message?.includes('ProcessTransport is not ready') ||\n    reason?.message?.includes('Stream can only be iterated once')\n  ) {\n    return;\n  }\n  // Log other unhandled rejections\n  console.error('Unhandled rejection:', reason);\n  process.exit(1);\n});\n\n// Prevent uncaught exceptions from showing during graceful shutdown\nprocess.on('uncaughtException', (error: Error) => {\n  // Ignore ProcessTransport errors during shutdown\n  if (\n    error.message?.includes('ProcessTransport is not ready') ||\n    error.message?.includes('Stream can only be iterated once')\n  ) {\n    return;\n  }\n  // Log other uncaught exceptions\n  console.error('Uncaught exception:', error);\n  process.exit(1);\n});\n\nyargs(hideBin(process.argv))\n  .env('RAINDROP')\n  // global options\n  .options({\n    debug: {\n      default: false,\n      describe: 'Enable verbose logging\\nenv: RAINDROP_DEBUG',\n      type: 'boolean',\n    },\n    default: {\n      default: false,\n      describe: 'Use default options for all prompts\\nenv: RAINDROP_DEFAULT',\n      type: 'boolean',\n    },\n  })\n  .command(\n    ['$0'],\n    'Run the Raindrop setup wizard',\n    (yargs) => {\n      return yargs.options({\n        'force-install': {\n          default: false,\n          describe:\n            'Force install packages even if peer dependency checks fail\\nenv: RAINDROP_FORCE_INSTALL',\n          type: 'boolean',\n        },\n        'install-dir': {\n          describe:\n            'Directory to install Raindrop in\\nenv: RAINDROP_INSTALL_DIR',\n          type: 'string',\n        },\n      });\n    },\n    (argv) => {\n      const options = { ...argv };\n\n      // TTY check - must use console before Ink is initialized\n      if (isNonInteractiveEnvironment()) {\n        red(\n          'Raindrop wizard requires an interactive terminal (TTY) to run.\\n' +\n            'It appears you are running in a non-interactive environment.\\n' +\n            'Please run the Raindrop wizard in an interactive terminal.',\n        );\n        process.exit(1);\n      }\n\n      // Run the async wizard logic\n      void (async () => {\n        // Initialize the unified Ink app (single render call)\n        const wizardUI = await initWizardUI();\n\n        // Handle Ctrl+C gracefully - exit without showing SDK cleanup errors\n        let sigintCount = 0;\n        const handleSIGINT = () => {\n          sigintCount++;\n          if (sigintCount === 1) {\n            // First Ctrl+C - let the agent handle it gracefully\n            // The agent-interface.ts will handle the interrupt\n            return;\n          }\n          // Second Ctrl+C - force exit immediately\n          wizardUI.unmount();\n          process.exit(130); // Standard exit code for SIGINT\n        };\n        process.on('SIGINT', handleSIGINT);\n\n        // Display logo through Ink\n        ui.addItem({ type: 'logo', text: '' });\n\n        try {\n          await runWizard(options as unknown as WizardOptions);\n          wizardUI.unmount();\n          process.removeListener('SIGINT', handleSIGINT);\n          process.exit(0);\n        } catch (error) {\n          ui.addItem({\n            type: 'error',\n            text: `Error: ${\n              error instanceof Error ? error.message : String(error)\n            }`,\n          });\n          wizardUI.unmount();\n          process.exit(1);\n        }\n\n        // The wizard completes - unmount the UI\n        // (cleanup is handled in the try/catch above)\n      })();\n    },\n  )\n  .help()\n  .alias('help', 'h')\n  .version()\n  .alias('version', 'v')\n  .wrap(null) // null = use terminal width automatically\n  .parse();\n"]}

package/dist/src/docs/browser.md

@@ -0,0 +1,105 @@
+---
+title: 'Browser (JavaScript)'
+description:
+  'Minimal browser-safe SDK for tracking AI events via /v1/events from web apps.'
+---
+
+### **Installation**
+
+Install the browser SDK package:
+
+<CodeGroup>
+
+```bash npm
+npm install @raindrop-ai/browser-sdk
+```
+
+```bash yarn
+yarn add @raindrop-ai/browser-sdk
+```
+
+```bash bun
+bun add @raindrop-ai/browser-sdk
+```
+
+</CodeGroup>
+
+### **Quickstart**
+
+```ts
+import { Raindrop } from '@raindrop-ai/browser-sdk';
+
+const rd = new Raindrop({ apiKey: RAINDROP_WRITE_KEY,  // Your project's Raindrop write key
+                          wizardSession: '__WIZARD_SESSION_UUID__' // REQUIRED
+                        });
+
+// 1) Single-shot AI event (camelCase fields)
+// Note: `input` and `output` should be the actual prompt sent to and response
+// received from your AI model - not literal placeholder strings.
+const { eventIds } = await rd.trackAi({
+  event: 'chat_message',
+  userId: userId, // Required: unique user ID string (e.g. user ID, email, auth sub; or generate one if not available)
+  model: modelName,
+  input: userPrompt, // The actual prompt sent to the model
+  output: modelResponse, // The actual response from the model
+  convoId: convId, // Conversation ID—set to how your app tracks/chat threads
+  properties: { exampleKey: 'exampleValue' },
+});
+console.log('trackAi eventIds:', eventIds);
+
+// 2) Partial AI event flow (for streaming responses)
+// Pass each chunk as it arrives, then call finish() with the complete response.
+const eid = uuidv4(); // import { v4 as uuidv4 } from 'uuid' — avoid Node 'crypto' module in browser/bundler environments
+const partial = await rd.trackAiPartial({
+  eventId: eid,
+  event: 'chat_message',
+  userId: userId, // Required: unique user ID string (e.g. user ID, email, auth sub; or generate one if not available)
+  model: modelName,
+  convoId: convId, // Conversation ID—set to how your app tracks/chat threads
+  output: chunk, // First streamed chunk from the model
+});
+
+await rd.trackAiPartial({ eventId: eid, output: nextChunk });
+const done = await partial.finish({ output: fullResponse }); // Complete response
+console.log('partial finished:', done);
+```
+
+### **Identify users**
+
+```ts
+// Associate traits with the current user — use actual user data from your app
+await rd.identify({
+  userId: userId, // The authenticated user's unique identifier
+  traits: {
+    name: userName,    // User's display name from your app
+    email: userEmail,  // User's email from your app
+    plan: userPlan,    // e.g. 'free', 'pro', 'enterprise'
+  },
+});
+
+// batch — replace with actual user data from your system
+await rd.identify([
+  { userId: userIdA, traits: { plan: planA } },
+  { userId: userIdB, traits: { plan: planB } },
+]);
+```
+
+### **Signals**
+
+```ts
+// thumbs down with a comment
+await rd.trackSignal({
+  eventId: eid,
+  name: 'thumbs_down',
+  type: 'feedback',
+  comment: 'Answer was off-topic',
+});
+
+// edit signal capturing the corrected content
+await rd.trackSignal({
+  eventId: eid,
+  name: 'edit',
+  type: 'edit',
+  after: 'the corrected final text',
+});
+```