notifkit 0.1.3 → 0.1.5

package/drizzle/meta/_journal.json

@@ -15,6 +15,27 @@
       "when": 1786643990078,
       "tag": "0001_stale_shotgun",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1788339340939,
+      "tag": "0002_wide_colleen_wing",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1788779801992,
+      "tag": "0003_skinny_daimon_hellstrom",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1788780502388,
+      "tag": "0004_pretty_bruce_banner",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notifkit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Self-hosted notification infrastructure. One call delivers to email, SMS, push, and webhook — routed by preference, quiet hours, and consent.",
   "license": "MIT",
   "author": "devkitshq",
@@ -46,13 +46,19 @@
   },
   "files": [
     "dist",
+    "src",
     "drizzle",
+    "scripts/create-project.mjs",
     "README.md",
     "LICENSE"
   ],
+  "bin": {
+    "notifkit-create-project": "./scripts/create-project.mjs"
+  },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "create-project": "node scripts/create-project.mjs",
     "test": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint . --fix",

package/scripts/create-project.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Create a project and print its API key.
+ *
+ * Every `/v1/*` route needs a project API key, and a project API key can only
+ * be minted with the admin credential, so this is the one bootstrap step
+ * between a running server and the first notification.
+ *
+ *   ADMIN_API_KEY=supersecretkey npm run create-project
+ *   ADMIN_API_KEY=supersecretkey npx notifkit-create-project "my-app"
+ *
+ * ADMIN_API_KEY is the same variable the server reads, so pass the value the
+ * server was started with.
+ */
+
+const adminKey = process.env.ADMIN_API_KEY;
+const baseUrl = (process.env.NOTIFKIT_URL || "http://localhost:3000").replace(/\/$/, "");
+const name = process.argv[2] || process.env.PROJECT_NAME || "my-app";
+
+function fail(message) {
+  console.error(`create-project: ${message}`);
+  process.exit(1);
+}
+
+if (!adminKey) {
+  fail(
+    "no admin credential. Set ADMIN_API_KEY to the same value the server was started with:\n" +
+      "  ADMIN_API_KEY=supersecretkey npm run create-project",
+  );
+}
+
+let res;
+try {
+  res = await fetch(`${baseUrl}/v1/projects`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${adminKey}` },
+    body: JSON.stringify({ name }),
+  });
+} catch (err) {
+  fail(`could not reach the server at ${baseUrl} — is it running? (${err.message})`);
+}
+
+if (res.status === 401) {
+  fail("admin credential rejected. It must match the server's ADMIN_API_KEY exactly.");
+}
+
+if (res.status === 403) {
+  fail("project management is disabled. Start the server with ADMIN_API_KEY set.");
+}
+
+if (!res.ok) {
+  fail(`server returned ${res.status}: ${await res.text()}`);
+}
+
+const { id, apiKey } = await res.json();
+
+// The server keeps only a hash of the key, so this is the only time the value
+// itself exists anywhere. Print it in .env form to make that the obvious move.
+console.log(`\nProject "${name}" created. Save the API key now — it is not recoverable.\n`);
+console.log(`NOTIFKIT_PROJECT_ID=${id}`);
+console.log(`NOTIFKIT_API_KEY=${apiKey}\n`);

package/src/client.ts

@@ -0,0 +1,412 @@
+import type {
+  AddUserInput,
+  UpdateUserInput,
+  AddContactInput,
+  SyncTemplatesInput,
+  NotifyRequestInput,
+  TriggerWorkflowInput,
+  CreateWorkflowInput,
+  IngestEventInput,
+  UpdateProjectInput,
+} from "./contracts/sdk.js";
+
+export interface NotifkitClientOptions {
+  baseUrl: string;
+  headers?: Record<string, string>;
+  templates?: SyncTemplatesInput["templates"];
+  apiKey?: string;
+}
+
+export class NotifkitClient {
+  private readonly options: NotifkitClientOptions;
+  private readonly baseUrl: string;
+  private readonly headers: Record<string, string>;
+
+  constructor(options: NotifkitClientOptions) {
+    this.options = options;
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.headers = {
+      "Content-Type": "application/json",
+      ...(options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {}),
+      ...options.headers,
+    };
+  }
+
+  private async request<T>(path: string, method: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (res.status === 204) {
+      return undefined as T;
+    }
+
+    const data = await res.json();
+    if (!res.ok) {
+      const errorMsg =
+        (data as any).message || (data as any).error || `Request failed with status ${res.status}`;
+      throw new Error(errorMsg);
+    }
+    return data as T;
+  }
+
+  /** Sync templates with the server. */
+  async syncTemplates(input: SyncTemplatesInput): Promise<{ synced: number }> {
+    return this.request("/v1/templates", "PUT", input);
+  }
+
+  /** Create/upsert a user profile and contacts. */
+  async addUser(input: AddUserInput): Promise<{ id: string }> {
+    return this.request("/v1/users", "POST", input);
+  }
+
+  /** Update user profile. */
+  async updateUser(id: string, input: UpdateUserInput): Promise<{ id: string }> {
+    return this.request(`/v1/users/${id}`, "PATCH", input);
+  }
+
+  /** Delete user profile. */
+  async deleteUser(id: string): Promise<void> {
+    return this.request(`/v1/users/${id}`, "DELETE");
+  }
+
+  /** Add contact targets to user profile. */
+  async addContact(
+    userId: string,
+    input: AddContactInput,
+  ): Promise<{ userId: string; channel: string; target: string }> {
+    return this.request(`/v1/users/${userId}/contacts`, "POST", input);
+  }
+
+  /** Delete a specific contact channel target. */
+  async deleteContact(userId: string, channel: string, target: string): Promise<void> {
+    return this.request(`/v1/users/${userId}/contacts/${channel}/${target}`, "DELETE");
+  }
+
+  /** Request a notification dispatch. */
+  async notify(
+    input: NotifyRequestInput,
+  ): Promise<{ messageId: string; notificationId: string; target: unknown }> {
+    return this.request("/v1/notify", "POST", input);
+  }
+
+  /** Trigger a registered background workflow. */
+  async triggerWorkflow(
+    input: TriggerWorkflowInput,
+  ): Promise<{ messageId: string; instanceId: string }> {
+    return this.request("/v1/workflows/trigger", "POST", input);
+  }
+
+  /** Create a dynamic JSON workflow definition. */
+  async createWorkflow(input: CreateWorkflowInput): Promise<{ name: string }> {
+    return this.request("/v1/workflows", "POST", input);
+  }
+
+  /** Ingest an external event into the system to resume workflows or trigger automations. */
+  async ingestEvent(input: IngestEventInput): Promise<{ messageId: string; eventId: string }> {
+    return this.request("/v1/events", "POST", input);
+  }
+
+  /** Sync templates configured on the client options to the server. */
+  async sync(): Promise<{ synced: number }> {
+    if (!this.options.templates || this.options.templates.length === 0) {
+      return { synced: 0 };
+    }
+    return this.syncTemplates({ templates: this.options.templates });
+  }
+
+  // ─── Missing Endpoints additions ─────────────────────────────────────────────
+
+  /** List registered workflow definitions. */
+  async listWorkflows(options?: {
+    limit?: number;
+    search?: string;
+  }): Promise<{ workflows: any[] }> {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", options.limit.toString());
+    if (options?.search) params.set("search", options.search);
+    const qs = params.toString();
+    return this.request(`/v1/workflows${qs ? `?${qs}` : ""}`, "GET");
+  }
+
+  /** Get a workflow instance by ID. */
+  async getWorkflow(instanceId: string): Promise<any> {
+    return this.request(`/v1/workflows/instances/${instanceId}`, "GET");
+  }
+
+  /** Cancel a running/suspended workflow instance. */
+  async cancelWorkflow(instanceId: string): Promise<void> {
+    return this.request(`/v1/workflows/instances/${instanceId}`, "DELETE");
+  }
+
+  /** Get notification logs for the project. */
+  async getNotificationLogs(options?: {
+    limit?: number;
+    cursor?: string;
+    templateId?: string;
+    workflowInstanceId?: string;
+    channel?: string;
+    status?: string;
+    taskId?: string;
+    campaign?: string;
+    search?: string;
+  }): Promise<{ logs: any[]; nextCursor: string | null }> {
+    let url = "/v1/notifications/logs";
+    if (options) {
+      const params = new URLSearchParams();
+      if (options.limit !== undefined) params.append("limit", options.limit.toString());
+      if (options.cursor) params.append("cursor", options.cursor);
+      if (options.templateId) params.append("templateId", options.templateId);
+      if (options.workflowInstanceId)
+        params.append("workflowInstanceId", options.workflowInstanceId);
+      if (options.channel) params.append("channel", options.channel);
+      if (options.status) params.append("status", options.status);
+      if (options.taskId) params.append("taskId", options.taskId);
+      if (options.campaign) params.append("campaign", options.campaign);
+      if (options.search) params.append("search", options.search);
+      const str = params.toString();
+      if (str) url += `?${str}`;
+    }
+    return this.request(url, "GET");
+  }
+
+  /** List/paginate users. */
+  async listUsers(options?: {
+    limit?: number;
+    cursor?: string;
+    search?: string;
+    segment?: string;
+    language?: string;
+    timezone?: string;
+    channel?: string;
+  }): Promise<{ users: any[]; nextCursor: string | null }> {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", options.limit.toString());
+    if (options?.cursor) params.set("cursor", options.cursor);
+    if (options?.search) params.set("search", options.search);
+    if (options?.segment) params.set("segment", options.segment);
+    if (options?.language) params.set("language", options.language);
+    if (options?.timezone) params.set("timezone", options.timezone);
+    if (options?.channel) params.set("channel", options.channel);
+    const qs = params.toString();
+    return this.request(`/v1/users${qs ? `?${qs}` : ""}`, "GET");
+  }
+
+  /** Delete a template. */
+  async deleteTemplate(id: string): Promise<void> {
+    return this.request(`/v1/templates/${id}`, "DELETE");
+  }
+
+  /** Get a user's contacts. */
+  async getUserContacts(userId: string): Promise<{ contacts: any[] }> {
+    return this.request(`/v1/users/${userId}/contacts`, "GET");
+  }
+
+  /** List projects (Admin only). */
+  async listProjects(): Promise<{ projects: any[] }> {
+    return this.request("/v1/projects", "GET");
+  }
+
+  /** Delete a project (Admin only). */
+  async deleteProject(id: string): Promise<void> {
+    return this.request(`/v1/projects/${id}`, "DELETE");
+  }
+
+  /** Create a new project API key (Admin only). */
+  async createProjectKey(
+    id: string,
+    input?: { role?: "admin" | "read_only" },
+  ): Promise<{ id: string; apiKey: string; role: string }> {
+    return this.request(`/v1/projects/${id}/keys`, "POST", input || {});
+  }
+
+  /** List project API keys (Admin only). */
+  async listProjectKeys(id: string): Promise<{ keys: any[] }> {
+    return this.request(`/v1/projects/${id}/keys`, "GET");
+  }
+
+  /** Delete a project API key (Admin only). */
+  async deleteProjectKey(id: string, keyId: string): Promise<void> {
+    return this.request(`/v1/projects/${id}/keys/${keyId}`, "DELETE");
+  }
+
+  /** Update project settings (Admin only). */
+  async updateProject(id: string, input: UpdateProjectInput): Promise<{ id: string }> {
+    return this.request(`/v1/projects/${id}`, "PATCH", input);
+  }
+
+  /** List unique segment tags. */
+  async listSegments(): Promise<{ segments: string[] }> {
+    return this.request("/v1/segments", "GET");
+  }
+
+  // ─── Campaigns ───────────────────────────────────────────────────────────────
+
+  /** List campaign labels seen in the delivery log, most recent activity first. */
+  async listCampaigns(options?: {
+    limit?: number;
+    search?: string;
+    channel?: string;
+    since?: string | Date;
+    until?: string | Date;
+    minMessages?: number;
+  }): Promise<{
+    campaigns: {
+      campaign: string;
+      messages: number;
+      firstSentAt: string;
+      lastActivityAt: string;
+    }[];
+  }> {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", String(options.limit));
+    if (options?.search) params.set("search", options.search);
+    if (options?.channel) params.set("channel", options.channel);
+    if (options?.since) {
+      params.set(
+        "since",
+        options.since instanceof Date ? options.since.toISOString() : options.since,
+      );
+    }
+    if (options?.until) {
+      params.set(
+        "until",
+        options.until instanceof Date ? options.until.toISOString() : options.until,
+      );
+    }
+    if (options?.minMessages) params.set("minMessages", String(options.minMessages));
+
+    const qs = params.toString();
+    return this.request(`/v1/campaigns${qs ? `?${qs}` : ""}`, "GET");
+  }
+
+  /** Delivery and engagement funnel for one campaign. */
+  async getCampaignStats(campaign: string): Promise<{
+    campaign: string;
+    totals: Record<string, number | null>;
+    byChannel: Record<string, Record<string, number>>;
+    engagementTracked: boolean;
+    warnings: string[];
+  }> {
+    return this.request(`/v1/campaigns/${encodeURIComponent(campaign)}/stats`, "GET");
+  }
+
+  // ─── Suppressions ────────────────────────────────────────────────────────────
+
+  /** List suppressed destinations. */
+  async listSuppressions(options?: {
+    limit?: number;
+    channel?: string;
+    reason?: string;
+    target?: string;
+  }): Promise<{ suppressions: any[] }> {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set("limit", options.limit.toString());
+    if (options?.channel) params.set("channel", options.channel);
+    if (options?.reason) params.set("reason", options.reason);
+    if (options?.target) params.set("target", options.target);
+    const qs = params.toString();
+    return this.request(`/v1/suppressions${qs ? `?${qs}` : ""}`, "GET");
+  }
+
+  /** Suppress a destination by hand. */
+  async createSuppression(input: {
+    channel: string;
+    target: string;
+    reason?: "unsubscribed" | "complained" | "bounced" | "manual";
+  }): Promise<{ channel: string; target: string; reason: string }> {
+    return this.request("/v1/suppressions", "POST", input);
+  }
+
+  /** Remove a suppression, re-enabling sends to that destination. */
+  async deleteSuppression(channel: string, target: string): Promise<void> {
+    return this.request(
+      `/v1/suppressions/${encodeURIComponent(channel)}/${encodeURIComponent(target)}`,
+      "DELETE",
+    );
+  }
+
+  // ─── Notification Status & Cancellation ─────────────────────────────────────
+
+  /** Get real-time status and delivery logs for a specific notification task. */
+  async getNotificationStatus(taskId: string): Promise<{ status: string; logs: any[] }> {
+    return this.request(`/v1/notifications/${encodeURIComponent(taskId)}`, "GET");
+  }
+
+  /** Cancel a scheduled notification task. */
+  async cancelNotification(taskId: string): Promise<{ success: boolean }> {
+    return this.request(`/v1/notifications/${encodeURIComponent(taskId)}`, "DELETE");
+  }
+
+  /** List pending scheduled messages. */
+  async getScheduledMessages(): Promise<{ scheduled: any[] }> {
+    return this.request("/v1/notifications/scheduled", "GET");
+  }
+
+  // ─── User Profile & Preferences ─────────────────────────────────────────────
+
+  /** Get user profile and contacts by ID. */
+  async getUser(id: string): Promise<any> {
+    return this.request(`/v1/users/${encodeURIComponent(id)}`, "GET");
+  }
+
+  /** Get user details including contacts and recent message logs. */
+  async getUserDetails(id: string): Promise<any> {
+    return this.request(`/v1/users/${encodeURIComponent(id)}/details`, "GET");
+  }
+
+  /** Get user preferences. */
+  async getUserPreferences(id: string): Promise<any> {
+    return this.request(`/v1/users/${encodeURIComponent(id)}/preferences`, "GET");
+  }
+
+  /** Update user preferences. */
+  async updateUserPreferences(
+    id: string,
+    preferences: Record<string, any>,
+  ): Promise<{ id: string; preferences: any }> {
+    return this.request(`/v1/users/${encodeURIComponent(id)}/preferences`, "PATCH", preferences);
+  }
+
+  // ─── Templates Querying ─────────────────────────────────────────────────────
+
+  /** List all templates for the project. */
+  async listTemplates(): Promise<{ templates: any[] }> {
+    return this.request("/v1/templates", "GET");
+  }
+
+  /** Get a template by ID. */
+  async getTemplate(id: string): Promise<any> {
+    return this.request(`/v1/templates/${encodeURIComponent(id)}`, "GET");
+  }
+
+  // ─── System Health, Metrics & DLQ ───────────────────────────────────────────
+
+  /** Get system health and worker status. */
+  async getSystemHealth(): Promise<any> {
+    return this.request("/v1/system/health", "GET");
+  }
+
+  /** Get system metrics and queue lengths. */
+  async getSystemMetrics(): Promise<any> {
+    return this.request("/v1/system/metrics", "GET");
+  }
+
+  /** Get dead-letter queue messages. */
+  async getDLQMessages(): Promise<{ messages: any[] }> {
+    return this.request("/v1/dlq", "GET");
+  }
+
+  /** Replay a dead-letter queue message. */
+  async replayDLQMessage(id: string): Promise<{ success: boolean; replayedId: string }> {
+    return this.request("/v1/dlq/replay", "POST", { id });
+  }
+
+  /** Delete a dead-letter queue message. */
+  async deleteDLQMessage(id: string): Promise<{ success: boolean }> {
+    return this.request(`/v1/dlq/${encodeURIComponent(id)}`, "DELETE");
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,107 @@
+import { config } from "dotenv";
+import { resolve } from "node:path";
+import { z, type ZodTypeAny } from "zod";
+import type { LanguageModel } from "ai";
+
+import { ValidationError } from "@/index.js";
+
+export function loadEnv(path?: string): void {
+  const envPath = path ?? resolve(process.cwd(), ".env");
+  config({ path: envPath, override: false });
+}
+
+export function parseConfig<TSchema extends ZodTypeAny>(
+  schema: TSchema,
+  data: unknown,
+): z.output<TSchema> {
+  const result = schema.safeParse(data);
+
+  if (!result.success) {
+    const fields: Record<string, string[]> = {};
+
+    for (const issue of result.error.issues) {
+      const key = issue.path.join(".");
+      fields[key] ??= [];
+      fields[key].push(issue.message);
+    }
+
+    throw new ValidationError("Configuration validation failed", fields);
+  }
+
+  return result.data;
+}
+
+export const baseConfigSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace", "silent"]).default("info"),
+  PORT: z.coerce.number().int().min(1).max(65_535).default(3000),
+  HOST: z.string().default("127.0.0.1"),
+  REDIS_URL: z.string().url().default("redis://localhost:6379"),
+  DATABASE_URL: z.string().url().default("postgres://platform:platform@localhost:5432/notifkit"),
+  ADMIN_API_KEY: z.string().optional(),
+  WORKER_CONCURRENCY: z.coerce.number().int().min(1).default(10),
+  QUEUE_MAX_LEN: z.coerce.number().int().min(1).default(10000000),
+  DB_MAX_CONNECTIONS: z.coerce.number().int().min(1).default(2),
+  LOG_FLUSH_INTERVAL_MS: z.coerce.number().int().min(50).default(500),
+  LOG_BUFFER_MAX_SIZE: z.coerce.number().int().min(100).default(5000),
+  SEGMENT_MAX_USERS: z.coerce.number().int().min(1).default(10000),
+  /**
+   * Externally reachable base URL of this API. Unsubscribe links are built from
+   * it, so it must be what an inbox can actually reach — not `HOST`/`PORT`,
+   * which describe the bind address behind your proxy.
+   */
+  PUBLIC_URL: z.string().url().optional(),
+  /**
+   * Signing key for unsubscribe tokens. Rotating it invalidates every
+   * unsubscribe link already sitting in someone's inbox, so treat it as
+   * permanent: a dead link means the recipient reaches for the spam button
+   * instead, which costs far more than the key ever protected.
+   */
+  UNSUBSCRIBE_SECRET: z.string().min(16).optional(),
+});
+
+export type BaseConfig = z.infer<typeof baseConfigSchema>;
+
+let globalConfig: BaseConfig | null = null;
+
+export function setGlobalConfig(config: BaseConfig) {
+  globalConfig = config;
+}
+
+export function readBaseConfig(data: NodeJS.ProcessEnv = process.env): BaseConfig {
+  if (globalConfig) {
+    return globalConfig;
+  }
+  return parseConfig(baseConfigSchema, data);
+}
+
+export interface RateLimitConfig {
+  limit: number;
+  windowSeconds: number;
+}
+
+export interface AiConfig {
+  aiModel?: LanguageModel;
+  /** Hard cap on generated tokens per prompt. Bounds cost and email size. */
+  maxOutputTokens?: number;
+  /** Wall-clock budget for a single generation before it is aborted. */
+  timeoutMs?: number;
+  /** Max prompts executed for one notification. */
+  maxPromptsPerNotification?: number;
+}
+
+export const AI_DEFAULTS = {
+  maxOutputTokens: 1_000,
+  timeoutMs: 30_000,
+  maxPromptsPerNotification: 5,
+} as const;
+
+let globalAiConfig: AiConfig = {};
+
+export function setAiConfig(config: AiConfig) {
+  globalAiConfig = config;
+}
+
+export function getAiConfig(): AiConfig {
+  return globalAiConfig;
+}

package/src/contracts/common.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const NotificationChannelSchema = z.enum([
+  "email",
+  "sms",
+  "push",
+  "webhook",
+  "in-app",
+  "telegram",
+  "discord",
+  "whatsapp",
+  "slack",
+]);
+export type NotificationChannel = z.infer<typeof NotificationChannelSchema>;
+
+export const NotificationPrioritySchema = z.enum(["low", "normal", "high", "critical"]);
+export type NotificationPriority = z.infer<typeof NotificationPrioritySchema>;
+
+export const NotificationStatusSchema = z.enum([
+  "pending",
+  "queued",
+  "processing",
+  "delivered",
+  "failed",
+  "bounced",
+  "suppressed",
+]);
+export type NotificationStatus = z.infer<typeof NotificationStatusSchema>;