@flicknote/integration-utils

Shared KV utilities for FlickNote integrations with Cloudflare Workers.

Installation

npm install @flicknote/integration-utils

Integration-Specific Dependencies

This package uses optional peer dependencies - only install what you need:

For Notion Integration

npm install @notionhq/client @tryfabric/martian

For Telegram Integration

npm install nanoid

For Both Integrations

npm install @notionhq/client @tryfabric/martian nanoid

Usage

Core Setup

import { KeyBuilder } from '@flicknote/integration-utils/core';

// Initialize KeyBuilder with your key patterns
const keyBuilder = new KeyBuilder(yourKeyPatterns);

Notion Integration

⚠️ Requires: @notionhq/client and @tryfabric/martian

import { NotionKVOperations } from '@flicknote/integration-utils/integrations/notion';

const notionOps = new NotionKVOperations(kv, keyBuilder);

// OAuth flow
await notionOps.storeOAuthState(state, userId);
const userId = await notionOps.verifyOAuthState(state);

try {
  const result = await notionOps.setCompleteIntegration(
    userId, code, clientId, clientSecret, redirectUri
  );
  // page_id automatically saved to settings
} catch (error) {
  if (error instanceof NotionPageValidationError) {
    console.error(`Please share exactly 1 page, got ${error.pageCount}`);
  }
}

// Create notes
await notionOps.createNote(userId, {
  title: "My Note",
  content: "Content in **markdown**",
  summary: "Summary",
  keywords: ["tag1"],
  tags: ["category"],
  created_at: new Date().toISOString()
});

📖 Full documentation: See notion.md

Telegram Integration

⚠️ Requires: nanoid

import { TelegramKVOperations } from '@flicknote/integration-utils/integrations/telegram';

const telegramOps = new TelegramKVOperations(kv, keyBuilder);

// Generate binding code
const { code, expiresIn } = await telegramOps.generateBinding(userId);

// Link Telegram user
await telegramOps.linkTelegramUser(userId, telegramId, username);

// Get user mappings
const telegramId = await telegramOps.getTelegramId(userId);
const userId = await telegramOps.getUserId(telegramId);

// Settings management
const settings = await telegramOps.getSettings(userId);
await telegramOps.updateSettings(userId, { send_confirmation: false });

Key Patterns

Each integration provides key patterns for KV storage:

import { notionKeyPatterns } from '@flicknote/integration-utils/integrations/notion';
import { telegramKeyPatterns } from '@flicknote/integration-utils/integrations/telegram';

// Register patterns with your KeyBuilder
const keyBuilder = new KeyBuilder({
  ...notionKeyPatterns,
  ...telegramKeyPatterns,
  // your custom patterns
});

TypeScript Support

Full TypeScript support with exported types:

import type {
  NotionIntegrationData,
  NotionSettings,
  NoteData,
  BatchNoteResult
} from '@flicknote/integration-utils/integrations/notion';

import type {
  TelegramIntegrationData,
  TelegramSettings,
  BindingCodeData
} from '@flicknote/integration-utils/integrations/telegram';

Error Handling

import {
  NotionPageValidationError,
  NotionIntegrationError
} from '@flicknote/integration-utils/integrations/notion';

try {
  await notionOps.setCompleteIntegration(...);
} catch (error) {
  if (error instanceof NotionPageValidationError) {
    // User shared wrong number of pages
    console.error(`Expected 1 page, got ${error.pageCount}`);
  }
}

Cloudflare Workers Integration

This package is designed for Cloudflare Workers:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const kv = env.INTEGRATION_BINDING; // Your KV namespace
    const keyBuilder = new KeyBuilder(keyPatterns);

    const notionOps = new NotionKVOperations(kv, keyBuilder);
    // Use the operations...
  }
};

License

MIT

Contributing

Issues and pull requests are welcome at GitHub.