@marinade.finance/ts-subscription-client 1.0.0-beta.1

package/README.md

@@ -0,0 +1,107 @@
+# ts-subscription-client
+
+TypeScript client for the Marinade notification subscription API.
+Allows users to subscribe/unsubscribe to notifications and list
+active subscriptions.
+
+## Usage
+
+```typescript
+import {
+  createSubscriptionClient,
+  subscribeMessage,
+  unsubscribeMessage,
+  listSubscriptionsMessage,
+} from '@marinade.finance/ts-subscription-client'
+
+const client = createSubscriptionClient({
+  base_url: 'https://notifications.marinade.finance',
+})
+```
+
+The message format is built by helper functions (`subscribeMessage`,
+`unsubscribeMessage`, `listSubscriptionsMessage`). Each request
+includes a signature and message for server-side authentication.
+
+For local development and testing subscriptions end-to-end, see
+[notification-service/DEV_GUIDE.md](../notification-service/DEV_GUIDE.md).
+
+## Channels
+
+A "channel" is a delivery medium for notifications. Each subscription
+binds a user to a channel + address pair.
+
+### telegram
+
+Telegram subscriptions use a deep-link activation flow:
+
+1. **Subscribe** — the client sends a `POST /subscriptions` request
+   with `channel=telegram`. The server creates a subscription with
+   `telegram_status='pending'` and returns a `deep_link` in the
+   response (e.g., `https://t.me/MarinadeBot?start=feature_sam_auction-<uuid>`).
+
+2. **Activate** — the user opens the deep link in Telegram and
+   presses "Start". The telegram-bot processes the link and maps
+   the user's chat to the subscription. From this point on,
+   notifications are delivered as Telegram messages.
+
+The `telegram_status` field tracks delivery state:
+`pending` → `active` → `inactive` / `unsubscribed` / `blocked`
+
+### api
+
+The API channel stores notifications in a server-side outbox.
+Clients pull them via the read API (notifications endpoint).
+No activation step is needed — subscribing is sufficient.
+
+## Notification types
+
+### sam_auction
+
+SAM auction notifications for validators. Subscribing requires
+proof of authority over a bond — the signer must be the bond
+authority, validator identity, or vote account owner. The server
+verifies this against on-chain bond accounts.
+
+The `additional_data` field for subscribe/unsubscribe should include:
+
+```typescript
+{
+  config_address: string // bonds program config
+  vote_account: string // validator vote account
+  bond_pubkey: string // derived bond PDA
+}
+```
+
+For listing subscriptions (`GET /subscriptions`), no `additional_data`
+is needed — the server performs a reverse lookup from the pubkey.
+
+## Known limitations
+
+### Telegram subscription lifecycle
+
+The notification service tracks `telegram_status` for each telegram subscription:
+`pending` → `active` → `inactive` / `unsubscribed` / `blocked`.
+
+The consumer filters by `telegram_status` before attempting delivery.
+It does not attempt to send notifications to subscriptions marked as `inactive`,
+`unsubscribed`, or `blocked`. The status is updated based on the telegram-bot's
+`/send` response:
+
+- **200** → `active` (message delivered)
+- **404** → `inactive` (subscription never existed in telegram-bot — bad external_id)
+- **410 "Subscription inactive"** → `unsubscribed` (user unsubscribed via bot UI)
+- **410 "User blocked bot"** → `blocked` (user blocked the bot in Telegram)
+- **429 / 5xx** → retry with backoff, status unchanged
+
+#### Re-subscribe after unsubscribe or block
+
+When a user unsubscribes via the Telegram bot UI or blocks the bot, the
+notification service marks the subscription as `unsubscribed` or `blocked` and
+stops delivery. Clicking the original Telegram deep link again reactivates the
+subscription on the telegram-bot side, but the notification service is not
+notified — it still sees the old status and skips delivery.
+
+To re-subscribe, the user must use the **CLI subscribe command**. This calls
+`POST /subscriptions` which resets `telegram_status` to `pending`, allowing
+delivery to resume on the next event.

package/__tests__/client.e2e.ts

@@ -0,0 +1,245 @@
+import http from 'http'
+
+import { createSubscriptionClient, NetworkError } from '../index'
+
+import type { SubscriptionClient } from '../index'
+import type { IncomingMessage, ServerResponse } from 'http'
+
+let server: http.Server
+let port: number
+let client: SubscriptionClient
+
+function startServer(
+  handler: (req: IncomingMessage, res: ServerResponse) => void,
+): Promise<void> {
+  return new Promise(resolve => {
+    server = http.createServer(handler)
+    server.listen(0, () => {
+      const addr = server.address()
+      if (addr && typeof addr !== 'string') {
+        port = addr.port
+      }
+      client = createSubscriptionClient({
+        base_url: `http://localhost:${port}`,
+      })
+      resolve()
+    })
+  })
+}
+
+function stopServer(): Promise<void> {
+  return new Promise(resolve => {
+    server.close(() => resolve())
+  })
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise(resolve => {
+    let data = ''
+    req.on('data', (chunk: Buffer) => {
+      data += chunk.toString()
+    })
+    req.on('end', () => resolve(data))
+  })
+}
+
+describe('SubscriptionClient E2E', () => {
+  afterEach(async () => {
+    if (server) {
+      await stopServer()
+    }
+  })
+
+  describe('subscribe', () => {
+    it('sends POST with correct body and returns typed response', async () => {
+      let receivedBody: Record<string, unknown> | undefined
+      let receivedMethod: string | undefined
+
+      await startServer((req, res) => {
+        receivedMethod = req.method
+        void readBody(req).then(body => {
+          receivedBody = JSON.parse(body) as Record<string, unknown>
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(
+            JSON.stringify({
+              user_id: 'u1',
+              notification_type: 'sam_auction',
+              channel: 'telegram',
+              channel_address: '@test',
+              created_at: '2024-01-01',
+              deep_link: 'https://t.me/bot?start=abc',
+            }),
+          )
+        })
+      })
+
+      const result = await client.subscribe({
+        pubkey: 'pk1',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        channel_address: '@test',
+        signature: 'sig1',
+        message: 'Subscribe sam_auction telegram 1710000000',
+        additional_data: { vote_account: 'va1' },
+      })
+
+      expect(receivedMethod).toBe('POST')
+      expect(receivedBody).toEqual({
+        pubkey: 'pk1',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        channel_address: '@test',
+        signature: 'sig1',
+        message: 'Subscribe sam_auction telegram 1710000000',
+        additional_data: { vote_account: 'va1' },
+      })
+      expect(result.deep_link).toBe('https://t.me/bot?start=abc')
+      expect(result.user_id).toBe('u1')
+    })
+  })
+
+  describe('unsubscribe', () => {
+    it('sends DELETE with correct body', async () => {
+      let receivedMethod: string | undefined
+      let receivedBody: Record<string, unknown> | undefined
+
+      await startServer((req, res) => {
+        receivedMethod = req.method
+        void readBody(req).then(body => {
+          receivedBody = JSON.parse(body) as Record<string, unknown>
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ deleted: true }))
+        })
+      })
+
+      const result = await client.unsubscribe({
+        pubkey: 'pk1',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        signature: 'sig1',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
+      })
+
+      expect(receivedMethod).toBe('DELETE')
+      expect(receivedBody?.channel_address).toBeUndefined()
+      expect(result.deleted).toBe(true)
+    })
+
+    it('sends DELETE with channel_address when provided', async () => {
+      let receivedBody: Record<string, unknown> | undefined
+
+      await startServer((req, res) => {
+        void readBody(req).then(body => {
+          receivedBody = JSON.parse(body) as Record<string, unknown>
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ deleted: true }))
+        })
+      })
+
+      await client.unsubscribe({
+        pubkey: 'pk1',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        signature: 'sig1',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
+      })
+
+      expect(receivedBody?.channel_address).toBe('@testuser')
+    })
+  })
+
+  describe('listSubscriptions', () => {
+    it('sends GET with correct query params and auth headers', async () => {
+      let receivedUrl: string | undefined
+      let receivedHeaders: Record<string, string | undefined> | undefined
+
+      await startServer((req, res) => {
+        receivedUrl = req.url
+        receivedHeaders = {
+          'x-solana-signature': req.headers['x-solana-signature'] as string,
+          'x-solana-message': req.headers['x-solana-message'] as string,
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(
+          JSON.stringify([
+            {
+              user_id: 'u1',
+              notification_type: 'sam_auction',
+              channel: 'telegram',
+              channel_address: '@test',
+              created_at: '2024-01-01',
+            },
+          ]),
+        )
+      })
+
+      const result = await client.listSubscriptions(
+        {
+          pubkey: 'pk1',
+          notification_type: 'sam_auction',
+        },
+        {
+          signature: 'sig1',
+          message: 'ListSubscriptions pk1 1710000000',
+        },
+      )
+
+      expect(receivedUrl).toBe(
+        '/subscriptions?pubkey=pk1&notification_type=sam_auction',
+      )
+      expect(receivedHeaders).toEqual({
+        'x-solana-signature': 'sig1',
+        'x-solana-message': 'ListSubscriptions pk1 1710000000',
+      })
+      expect(result).toHaveLength(1)
+      expect(result[0].channel).toBe('telegram')
+    })
+  })
+
+  describe('error propagation', () => {
+    it.each([400, 401, 403, 404])(
+      'throws NetworkError with status %d',
+      async statusCode => {
+        await startServer((_req, res) => {
+          res.writeHead(statusCode, { 'Content-Type': 'text/plain' })
+          res.end(`error ${statusCode}`)
+        })
+
+        const error = await client
+          .subscribe({
+            pubkey: 'p',
+            notification_type: 'sam_auction',
+            channel: 'telegram',
+            channel_address: '@t',
+            signature: 's',
+            message: 'm',
+          })
+          .catch((e: unknown) => e)
+
+        expect(error).toBeInstanceOf(NetworkError)
+        expect((error as NetworkError).status).toBe(statusCode)
+        expect((error as NetworkError).response).toBe(`error ${statusCode}`)
+      },
+    )
+  })
+
+  describe('connection refused', () => {
+    it('throws NetworkError when server is unreachable', async () => {
+      const unreachableClient = createSubscriptionClient({
+        base_url: 'http://localhost:19999',
+      })
+
+      await expect(
+        unreachableClient.subscribe({
+          pubkey: 'p',
+          notification_type: 'sam_auction',
+          channel: 'telegram',
+          channel_address: '@t',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow(NetworkError)
+    })
+  })
+})

package/__tests__/client.test.ts

@@ -0,0 +1,348 @@
+import { createSubscriptionClient, NetworkError } from '../index'
+
+global.fetch = jest.fn()
+
+describe('SubscriptionClient', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  describe('subscribe', () => {
+    it('should send POST request with correct body', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      const responseBody = {
+        user_id: 'user-1',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        created_at: '2024-01-01T00:00:00Z',
+        deep_link: 'https://t.me/test',
+      }
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(responseBody),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      const request = {
+        pubkey: 'pubkey123',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        signature: 'sig123',
+        message: 'Subscribe sam_auction telegram 1710000000',
+        additional_data: { vote_account: 'vote123' },
+      }
+
+      const result = await client.subscribe(request)
+
+      expect(result).toEqual(responseBody)
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+      const [url, options] = mockFetch.mock.calls[0]
+      expect(url).toBe('http://localhost:3000/subscriptions')
+      expect(options?.method).toBe('POST')
+      expect(options?.headers).toEqual({ 'Content-Type': 'application/json' })
+      expect(JSON.parse(options?.body as string)).toEqual(request)
+    })
+
+    it('should throw NetworkError on HTTP error', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        text: () => Promise.resolve('validation failed'),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await expect(
+        client.subscribe({
+          pubkey: 'p',
+          notification_type: 'sam_auction',
+          channel: 'telegram',
+          channel_address: '@test',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow(NetworkError)
+    })
+
+    it('should throw NetworkError on network failure', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockRejectedValue(new Error('ECONNREFUSED'))
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await expect(
+        client.subscribe({
+          pubkey: 'p',
+          notification_type: 'sam_auction',
+          channel: 'telegram',
+          channel_address: '@test',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow('ECONNREFUSED')
+    })
+  })
+
+  describe('unsubscribe', () => {
+    it('should send DELETE request with correct body', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ deleted: true }),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      const request = {
+        pubkey: 'pubkey123',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        signature: 'sig123',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
+      }
+
+      const result = await client.unsubscribe(request)
+
+      expect(result).toEqual({ deleted: true })
+      const [url, options] = mockFetch.mock.calls[0]
+      expect(url).toBe('http://localhost:3000/subscriptions')
+      expect(options?.method).toBe('DELETE')
+      expect(JSON.parse(options?.body as string)).toEqual(request)
+    })
+
+    it('should include channel_address when provided', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ deleted: true }),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      const request = {
+        pubkey: 'pubkey123',
+        notification_type: 'sam_auction',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        signature: 'sig123',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
+      }
+
+      await client.unsubscribe(request)
+
+      const [, options] = mockFetch.mock.calls[0]
+      const body = JSON.parse(options?.body as string)
+      expect(body.channel_address).toBe('@testuser')
+    })
+
+    it('should throw NetworkError on HTTP error', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 403,
+        statusText: 'Forbidden',
+        text: () => Promise.resolve('unauthorized'),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await expect(
+        client.unsubscribe({
+          pubkey: 'p',
+          notification_type: 'sam_auction',
+          channel: 'telegram',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow(NetworkError)
+    })
+  })
+
+  describe('listSubscriptions', () => {
+    it('should send GET request with correct query params and auth headers', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      const responseBody = [
+        {
+          user_id: 'user-1',
+          notification_type: 'sam_auction',
+          channel: 'telegram',
+          channel_address: '@testuser',
+          created_at: '2024-01-01T00:00:00Z',
+        },
+      ]
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(responseBody),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      const result = await client.listSubscriptions(
+        {
+          pubkey: 'pubkey123',
+          notification_type: 'sam_auction',
+        },
+        {
+          signature: 'sig123',
+          message: 'ListSubscriptions pubkey123 1710000000',
+        },
+      )
+
+      expect(result).toEqual(responseBody)
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+      const [url, options] = mockFetch.mock.calls[0]
+      expect(url).toBe(
+        'http://localhost:3000/subscriptions?pubkey=pubkey123&notification_type=sam_auction',
+      )
+      expect(options?.method).toBe('GET')
+      expect(options?.headers).toEqual({
+        'x-solana-signature': 'sig123',
+        'x-solana-message': 'ListSubscriptions pubkey123 1710000000',
+      })
+    })
+
+    it('should include additional_data as JSON query param', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve([]),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await client.listSubscriptions(
+        {
+          pubkey: 'pubkey123',
+          notification_type: 'sam_auction',
+          additional_data: { vote_account: 'vote123' },
+        },
+        { signature: 'sig', message: 'msg' },
+      )
+
+      const [url] = mockFetch.mock.calls[0]
+      const parsed = new URL(url)
+      expect(parsed.searchParams.get('additional_data')).toBe(
+        JSON.stringify({ vote_account: 'vote123' }),
+      )
+    })
+
+    it('should omit additional_data when empty object', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve([]),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await client.listSubscriptions(
+        { pubkey: 'pubkey123', additional_data: {} },
+        { signature: 'sig', message: 'msg' },
+      )
+
+      const [url] = mockFetch.mock.calls[0]
+      const parsed = new URL(url)
+      expect(parsed.searchParams.get('additional_data')).toBeNull()
+    })
+
+    it('should omit optional query params when not provided', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve([]),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await client.listSubscriptions(
+        { pubkey: 'pubkey123' },
+        { signature: 'sig', message: 'msg' },
+      )
+
+      const [url] = mockFetch.mock.calls[0]
+      expect(url).toBe('http://localhost:3000/subscriptions?pubkey=pubkey123')
+    })
+
+    it('should throw NetworkError on HTTP error', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 401,
+        statusText: 'Unauthorized',
+        text: () => Promise.resolve('invalid signature'),
+      } as Response)
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+      })
+
+      await expect(
+        client.listSubscriptions(
+          { pubkey: 'p' },
+          { signature: 's', message: 'm' },
+        ),
+      ).rejects.toThrow(NetworkError)
+    })
+  })
+
+  describe('timeout', () => {
+    it('should throw NetworkError on timeout', async () => {
+      const mockFetch = global.fetch as jest.Mock
+      mockFetch.mockImplementation(
+        (_url: string, options: { signal: AbortSignal }) =>
+          new Promise((_resolve, reject) => {
+            options.signal.addEventListener('abort', () => {
+              const err = new Error('The operation was aborted')
+              err.name = 'AbortError'
+              reject(err)
+            })
+          }),
+      )
+
+      const client = createSubscriptionClient({
+        base_url: 'http://localhost:3000',
+        timeout_ms: 50,
+      })
+
+      await expect(
+        client.subscribe({
+          pubkey: 'p',
+          notification_type: 'sam_auction',
+          channel: 'telegram',
+          channel_address: '@test',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow(/timeout/)
+    })
+  })
+})