Node.js SDK

Installation

Install

npm install @notilens/notilens
# or
yarn add @notilens/notilens

Setup

Initialize

import { NotiLens } from '@notilens/notilens';

// Pass credentials directly
const nl = NotiLens.init('my-app', {
  token: 'YOUR_TOKEN',
  secret: 'YOUR_SECRET'
});

// Or use environment variables: NOTILENS_TOKEN / NOTILENS_SECRET
const nl = NotiLens.init('my-app');

// Multiple sources
const scraper = NotiLens.init('scraper', { token: 'TOKEN_A', secret: 'SECRET_A' });
const mailer  = NotiLens.init('mailer',  { token: 'TOKEN_B', secret: 'SECRET_B' });

Notify

Notify

nl.notify('order.placed', 'Order #1234');
nl.notify('disk.space.full', 'Only 1GB left', { level: 'warning' });
nl.notify('report.ready', 'Your report is ready', {
  downloadUrl: 'https://example.com/report.pdf',
  tags: 'report,weekly',
});

Task Lifecycle

Task Events

const run = nl.task('email');
run.queue();
run.start();

run.progress('Fetching records...');
run.loop('Processing batch 2');
run.retry();
run.pause('Rate limited');
run.resume('Resuming');
run.wait('Awaiting tool');
run.error('Non-fatal error');

// Terminal — pick one
run.complete('All done');
run.fail('Unrecoverable');
run.timeout('Exceeded 30s');
run.cancel('User cancelled');
run.terminate('OOM');

Input & Output

Input & Output Events

Real-world uses: AI drafts a blog post → outputGenerated → editor approves or rejects. AI generates an invoice → inputRequired → finance confirms → sends.

Human-in-the-loop

run.inputRequired('Please confirm the output');
run.inputApproved('User confirmed');
run.inputRejected('User rejected');

Output events

run.outputGenerated('Summary ready');
run.outputFailed('Model timeout');

Metrics

Metrics

run.metric('tokens', 350);
run.metric('tokens', 210);   // now 560 — numeric values accumulate
run.metric('cost', 0.0012);
run.metric('model', 'gpt-4'); // strings replace, not accumulate

run.resetMetrics('tokens');  // reset one
run.resetMetrics();           // reset all

Custom Events

Custom / Generic Events

Real-world uses: Stripe payment arrives → track payment volume. User signs up mid-run → attach signup to the agent run that triggered it. Deploy finishes → monitor anomalies post-release.

// Source-level
nl.track('disk.space.full', 'Only 1GB remaining');
nl.track('order.placed', 'Order #1234', { meta: { amount: 99.99 } });

// Run-level
run.track('order.placed', 'Order #1234');
run.track('order.placed', 'Order #1234', { meta: { amount: 99.99 } });

Full Example

Complete Working Example

import { NotiLens } from '@notilens/notilens';

const nl  = NotiLens.init('summarizer', { token: 'TOKEN', secret: 'SECRET' });
const run = nl.task('report');
run.start();

try {
  run.progress('Fetching PDF');

  const result = await llm.complete(prompt);
  run.metric('tokens', result.usage.totalTokens);
  run.metric('cost', result.usage.cost);

  run.outputGenerated('Summary ready');
  run.complete('Done');
} catch (err) {
  run.fail(err.message);
}