URL Generation

buildUrl()

Build a notifly URL from validated field values.

signature

function buildUrl(
  service: string,
  fields: Record<string, string | number | boolean>,
): BuildUrlResult

BuildUrlResult

interface BuildUrlResult {
  success: boolean;
  url?: string;           // Present when success is true
  errors?: ValidationError[];  // Present when success is false
}

buildUrl() validates before building — if validation fails it returns errors instead of a URL.

Examples

typescript

import { buildUrl } from '@ambersecurityinc/notifly/builder';

// Discord
const result = buildUrl('discord', {
  webhook_id: '1234567890',
  webhook_token: 'abcdefghijklmnopqrst',
});
// → { success: true, url: 'discord://1234567890/abcdefghijklmnopqrst' }

// ntfy (public server)
const ntfy = buildUrl('ntfy', { topic: 'my-alerts' });
// → { success: true, url: 'ntfy://my-alerts' }

// ntfy (self-hosted)
const ntfySelf = buildUrl('ntfy', {
  topic: 'my-alerts',
  host: 'ntfy.myserver.com',
});
// → { success: true, url: 'ntfy://ntfy.myserver.com/my-alerts' }

// Validation failure
const bad = buildUrl('discord', { webhook_id: '', webhook_token: '' });
// → { success: false, errors: [{ field: 'webhook_id', message: 'Required' }, ...] }

decomposeUrl()

Decompose an existing notifly URL back into its service key and field values. Useful for the edit flow: load an existing URL → display a pre-filled form → user edits → rebuild.

signature

function decomposeUrl(url: string): DecomposeResult

DecomposeResult

interface DecomposeResult {
  success: boolean;
  service?: string;
  fields?: Record<string, string>;
  error?: string;
}

Examples

typescript

import { decomposeUrl } from '@ambersecurityinc/notifly/builder';

const result = decomposeUrl('discord://1234567890/mytoken');
// → {
//   success: true,
//   service: 'discord',
//   fields: {
//     webhook_id: '1234567890',
//     webhook_token: 'mytoken',
//   }
// }

const ntfy = decomposeUrl('ntfy://my-alerts');
// → { success: true, service: 'ntfy', fields: { topic: 'my-alerts' } }

// Unknown scheme
const bad = decomposeUrl('unknown://something');
// → { success: false, error: 'Unknown service scheme: unknown' }

Round-trip pattern

Decompose an existing URL, display a pre-filled edit form, then rebuild on save:

edit flow

import { decomposeUrl, validateFields, buildUrl } from '@ambersecurityinc/notifly/builder';

// Load existing URL
const { service, fields } = decomposeUrl(storedUrl);

// Pre-fill form with fields
// ... user edits ...

// On save
const errors = validateFields(service, updatedFields);
if (errors.length === 0) {
  const { url } = buildUrl(service, updatedFields);
  saveUrl(url);
}