@marinade.finance/ts-subscription-client 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# 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 two-phase activation flow:
+
+1. **Subscribe** — the client sends a `POST /subscriptions` request
+   with `channel=telegram`. The server creates a pending activation
+   record and returns a `deep_link` in the response
+   (e.g., `https://t.me/MarinadeBot?start=<token>`).
+   At this point the subscription exists but cannot receive messages.
+
+2. **Activate** — the user opens the deep link in Telegram and
+   presses "Start". The bot receives the token via its webhook,
+   links the user's Telegram chat to the subscription, and confirms
+   activation. From this point on, notifications are delivered as
+   Telegram messages.
+
+If the user has already activated, the response returns
+`telegram_status: 'already_activated'` instead of a new deep link.
+
+Blocking the bot automatically unsubscribes all Telegram
+subscriptions for that chat.
+
+### 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
+
+### bonds
+
+Bond risk notifications for validators in the SAM auction.
+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.

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: 'bonds',
+              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: 'bonds',
+        channel: 'telegram',
+        channel_address: '@test',
+        signature: 'sig1',
+        message: 'Subscribe bonds telegram 1710000000',
+        additional_data: { vote_account: 'va1' },
+      })
+
+      expect(receivedMethod).toBe('POST')
+      expect(receivedBody).toEqual({
+        pubkey: 'pk1',
+        notification_type: 'bonds',
+        channel: 'telegram',
+        channel_address: '@test',
+        signature: 'sig1',
+        message: 'Subscribe bonds 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: 'bonds',
+        channel: 'telegram',
+        signature: 'sig1',
+        message: 'Unsubscribe bonds 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: 'bonds',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        signature: 'sig1',
+        message: 'Unsubscribe bonds 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: 'bonds',
+              channel: 'telegram',
+              channel_address: '@test',
+              created_at: '2024-01-01',
+            },
+          ]),
+        )
+      })
+
+      const result = await client.listSubscriptions(
+        {
+          pubkey: 'pk1',
+          notification_type: 'bonds',
+        },
+        {
+          signature: 'sig1',
+          message: 'ListSubscriptions pk1 1710000000',
+        },
+      )
+
+      expect(receivedUrl).toBe(
+        '/subscriptions?pubkey=pk1&notification_type=bonds',
+      )
+      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: 'bonds',
+            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: 'bonds',
+          channel: 'telegram',
+          channel_address: '@t',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow(NetworkError)
+    })
+  })
+})

package/__tests__/client.test.ts

@@ -0,0 +1,300 @@
+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: 'bonds',
+        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: 'bonds',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        signature: 'sig123',
+        message: 'Subscribe bonds 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: 'bonds',
+          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: 'bonds',
+          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: 'bonds',
+        channel: 'telegram',
+        signature: 'sig123',
+        message: 'Unsubscribe bonds 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: 'bonds',
+        channel: 'telegram',
+        channel_address: '@testuser',
+        signature: 'sig123',
+        message: 'Unsubscribe bonds 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: 'bonds',
+          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: 'bonds',
+          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: 'bonds',
+        },
+        {
+          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=bonds',
+      )
+      expect(options?.method).toBe('GET')
+      expect(options?.headers).toEqual({
+        'x-solana-signature': 'sig123',
+        'x-solana-message': 'ListSubscriptions pubkey123 1710000000',
+      })
+    })
+
+    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: 'bonds',
+          channel: 'telegram',
+          channel_address: '@test',
+          signature: 's',
+          message: 'm',
+        }),
+      ).rejects.toThrow(/timeout/)
+    })
+  })
+})

package/__tests__/message.test.ts

@@ -0,0 +1,30 @@
+import {
+  subscribeMessage,
+  unsubscribeMessage,
+  listSubscriptionsMessage,
+} from '../index'
+
+describe('message helpers', () => {
+  it('subscribeMessage', () => {
+    expect(subscribeMessage('bonds', 'telegram', 1710000000)).toBe(
+      'Subscribe bonds telegram 1710000000',
+    )
+  })
+
+  it('unsubscribeMessage', () => {
+    expect(unsubscribeMessage('bonds', 'email', 1710000000)).toBe(
+      'Unsubscribe bonds email 1710000000',
+    )
+  })
+
+  it('listSubscriptionsMessage', () => {
+    expect(
+      listSubscriptionsMessage(
+        'GrxB8UaaaaaaaaaaaaaaAAAAAAAAAAAAAAAAAAAAAAAA',
+        1710000000,
+      ),
+    ).toBe(
+      'ListSubscriptions GrxB8UaaaaaaaaaaaaaaAAAAAAAAAAAAAAAAAAAAAAAA 1710000000',
+    )
+  })
+})

package/client.ts

@@ -0,0 +1,121 @@
+import {
+  type SubscriptionClientConfig,
+  type Logger,
+  type SubscribeRequest,
+  type SubscribeResponse,
+  type UnsubscribeRequest,
+  type UnsubscribeResponse,
+  type ListSubscriptionsQuery,
+  type ListSubscriptionsAuth,
+  type Subscription,
+  NetworkError,
+} from './types'
+
+const PATH_SUBSCRIPTIONS = '/subscriptions'
+
+export class SubscriptionClient {
+  private readonly base_url: string
+  private readonly timeout_ms: number
+  private readonly logger?: Logger
+
+  constructor(config: SubscriptionClientConfig) {
+    this.base_url = config.base_url
+    this.timeout_ms = config.timeout_ms ?? 10_000
+    this.logger = config.logger
+  }
+
+  async subscribe(request: SubscribeRequest): Promise<SubscribeResponse> {
+    this.logger?.debug(
+      `POST ${PATH_SUBSCRIPTIONS} body: ${JSON.stringify({
+        ...request,
+        signature: '[redacted]',
+      })}`,
+    )
+    return this.fetch<SubscribeResponse>(PATH_SUBSCRIPTIONS, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    })
+  }
+
+  async unsubscribe(request: UnsubscribeRequest): Promise<UnsubscribeResponse> {
+    this.logger?.debug(
+      `DELETE ${PATH_SUBSCRIPTIONS} body: ${JSON.stringify({
+        ...request,
+        signature: '[redacted]',
+      })}`,
+    )
+    return this.fetch<UnsubscribeResponse>(PATH_SUBSCRIPTIONS, {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    })
+  }
+
+  async listSubscriptions(
+    query: ListSubscriptionsQuery,
+    auth: ListSubscriptionsAuth,
+  ): Promise<Subscription[]> {
+    const params = new URLSearchParams()
+    params.set('pubkey', query.pubkey)
+    if (query.notification_type) {
+      params.set('notification_type', query.notification_type)
+    }
+    const path = `${PATH_SUBSCRIPTIONS}?${params.toString()}`
+
+    this.logger?.debug(`GET ${path} signature: [redacted]`)
+    return this.fetch<Subscription[]>(path, {
+      method: 'GET',
+      headers: {
+        'x-solana-signature': auth.signature,
+        'x-solana-message': auth.message,
+      },
+    })
+  }
+
+  private async fetch<T>(path: string, init: RequestInit): Promise<T> {
+    const url = `${this.base_url}${path}`
+    const method = init.method ?? 'GET'
+
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout_ms)
+
+    try {
+      const response = await globalThis.fetch(url, {
+        ...init,
+        signal: controller.signal,
+      })
+
+      clearTimeout(timeoutId)
+
+      if (!response.ok) {
+        const errorBody = await response.text().catch(() => 'unknown error')
+        throw new NetworkError(
+          `${method} ${path} failed: ` +
+            `${response.status} ${response.statusText}`,
+          response.status,
+          errorBody,
+        )
+      }
+
+      return (await response.json()) as T
+    } catch (error) {
+      clearTimeout(timeoutId)
+
+      if (error instanceof NetworkError) {
+        throw error
+      }
+
+      if (error instanceof Error) {
+        if (error.name === 'AbortError') {
+          throw new NetworkError(
+            `${method} ${path} timeout after ${this.timeout_ms}ms`,
+          )
+        }
+        throw new NetworkError(`${method} ${path} failed: ${error.message}`)
+      }
+
+      throw new NetworkError(`${method} ${path} failed: unknown error`)
+    }
+  }
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { type SubscriptionClientConfig, type SubscribeRequest, type SubscribeResponse, type UnsubscribeRequest, type UnsubscribeResponse, type ListSubscriptionsQuery, type ListSubscriptionsAuth, type Subscription } from './types';
+export declare class SubscriptionClient {
+    private readonly base_url;
+    private readonly timeout_ms;
+    private readonly logger?;
+    constructor(config: SubscriptionClientConfig);
+    subscribe(request: SubscribeRequest): Promise<SubscribeResponse>;
+    unsubscribe(request: UnsubscribeRequest): Promise<UnsubscribeResponse>;
+    listSubscriptions(query: ListSubscriptionsQuery, auth: ListSubscriptionsAuth): Promise<Subscription[]>;
+    private fetch;
+}

package/dist/client.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionClient = void 0;
+const types_1 = require("./types");
+const PATH_SUBSCRIPTIONS = '/subscriptions';
+class SubscriptionClient {
+    constructor(config) {
+        this.base_url = config.base_url;
+        this.timeout_ms = config.timeout_ms ?? 10000;
+        this.logger = config.logger;
+    }
+    async subscribe(request) {
+        this.logger?.debug(`POST ${PATH_SUBSCRIPTIONS} body: ${JSON.stringify({
+            ...request,
+            signature: '[redacted]',
+        })}`);
+        return this.fetch(PATH_SUBSCRIPTIONS, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(request),
+        });
+    }
+    async unsubscribe(request) {
+        this.logger?.debug(`DELETE ${PATH_SUBSCRIPTIONS} body: ${JSON.stringify({
+            ...request,
+            signature: '[redacted]',
+        })}`);
+        return this.fetch(PATH_SUBSCRIPTIONS, {
+            method: 'DELETE',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(request),
+        });
+    }
+    async listSubscriptions(query, auth) {
+        const params = new URLSearchParams();
+        params.set('pubkey', query.pubkey);
+        if (query.notification_type) {
+            params.set('notification_type', query.notification_type);
+        }
+        const path = `${PATH_SUBSCRIPTIONS}?${params.toString()}`;
+        this.logger?.debug(`GET ${path} signature: [redacted]`);
+        return this.fetch(path, {
+            method: 'GET',
+            headers: {
+                'x-solana-signature': auth.signature,
+                'x-solana-message': auth.message,
+            },
+        });
+    }
+    async fetch(path, init) {
+        const url = `${this.base_url}${path}`;
+        const method = init.method ?? 'GET';
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout_ms);
+        try {
+            const response = await globalThis.fetch(url, {
+                ...init,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorBody = await response.text().catch(() => 'unknown error');
+                throw new types_1.NetworkError(`${method} ${path} failed: ` +
+                    `${response.status} ${response.statusText}`, response.status, errorBody);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof types_1.NetworkError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    throw new types_1.NetworkError(`${method} ${path} timeout after ${this.timeout_ms}ms`);
+                }
+                throw new types_1.NetworkError(`${method} ${path} failed: ${error.message}`);
+            }
+            throw new types_1.NetworkError(`${method} ${path} failed: unknown error`);
+        }
+    }
+}
+exports.SubscriptionClient = SubscriptionClient;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { SubscriptionClient } from './client';
+import type { SubscriptionClientConfig } from './types';
+export { SubscriptionClient };
+export { subscribeMessage, unsubscribeMessage, listSubscriptionsMessage, } from './message';
+export { NetworkError } from './types';
+export type { Logger, SubscriptionClientConfig, SubscribeRequest, SubscribeResponse, UnsubscribeRequest, UnsubscribeResponse, ListSubscriptionsQuery, ListSubscriptionsAuth, Subscription, } from './types';
+export declare function createSubscriptionClient(config: SubscriptionClientConfig): SubscriptionClient;

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkError = exports.listSubscriptionsMessage = exports.unsubscribeMessage = exports.subscribeMessage = exports.SubscriptionClient = void 0;
+exports.createSubscriptionClient = createSubscriptionClient;
+const client_1 = require("./client");
+Object.defineProperty(exports, "SubscriptionClient", { enumerable: true, get: function () { return client_1.SubscriptionClient; } });
+var message_1 = require("./message");
+Object.defineProperty(exports, "subscribeMessage", { enumerable: true, get: function () { return message_1.subscribeMessage; } });
+Object.defineProperty(exports, "unsubscribeMessage", { enumerable: true, get: function () { return message_1.unsubscribeMessage; } });
+Object.defineProperty(exports, "listSubscriptionsMessage", { enumerable: true, get: function () { return message_1.listSubscriptionsMessage; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return types_1.NetworkError; } });
+function createSubscriptionClient(config) {
+    return new client_1.SubscriptionClient(config);
+}

package/dist/message.d.ts

@@ -0,0 +1,6 @@
+/** Builds the signed message string for subscribe operations */
+export declare function subscribeMessage(notificationType: string, channel: string, timestampSeconds: number): string;
+/** Builds the signed message string for unsubscribe operations */
+export declare function unsubscribeMessage(notificationType: string, channel: string, timestampSeconds: number): string;
+/** Builds the signed message string for listing subscriptions */
+export declare function listSubscriptionsMessage(pubkey: string, timestampSeconds: number): string;

package/dist/message.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subscribeMessage = subscribeMessage;
+exports.unsubscribeMessage = unsubscribeMessage;
+exports.listSubscriptionsMessage = listSubscriptionsMessage;
+/** Builds the signed message string for subscribe operations */
+function subscribeMessage(notificationType, channel, timestampSeconds) {
+    return `Subscribe ${notificationType} ${channel} ${timestampSeconds}`;
+}
+/** Builds the signed message string for unsubscribe operations */
+function unsubscribeMessage(notificationType, channel, timestampSeconds) {
+    return `Unsubscribe ${notificationType} ${channel} ${timestampSeconds}`;
+}
+/** Builds the signed message string for listing subscriptions */
+function listSubscriptionsMessage(pubkey, timestampSeconds) {
+    return `ListSubscriptions ${pubkey} ${timestampSeconds}`;
+}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../client.ts","../index.ts","../message.ts","../types.ts"],"version":"5.8.3"}

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+/** Minimal logger interface — compatible with pino, console, etc. */
+export interface Logger {
+    debug(msg: string): void;
+}
+/** Configuration for the subscription client */
+export interface SubscriptionClientConfig {
+    base_url: string;
+    timeout_ms?: number;
+    logger?: Logger;
+}
+/** POST /subscriptions request */
+export interface SubscribeRequest {
+    pubkey: string;
+    notification_type: string;
+    channel: string;
+    channel_address: string;
+    signature: string;
+    message: string;
+    additional_data?: Record<string, unknown>;
+}
+/** DELETE /subscriptions request */
+export interface UnsubscribeRequest {
+    pubkey: string;
+    notification_type: string;
+    channel: string;
+    channel_address?: string;
+    signature: string;
+    message: string;
+    additional_data?: Record<string, unknown>;
+}
+/** GET /subscriptions auth */
+export interface ListSubscriptionsAuth {
+    signature: string;
+    message: string;
+}
+/** GET /subscriptions query */
+export interface ListSubscriptionsQuery {
+    pubkey: string;
+    notification_type?: string;
+}
+/** POST /subscriptions response */
+export interface SubscribeResponse {
+    user_id: string;
+    notification_type: string;
+    channel: string;
+    channel_address: string;
+    created_at: string;
+    deep_link?: string;
+    telegram_status?: 'already_activated' | 'bot_not_configured';
+}
+/** DELETE /subscriptions response */
+export interface UnsubscribeResponse {
+    deleted: boolean;
+}
+/** GET /subscriptions response item */
+export interface Subscription {
+    user_id: string;
+    notification_type: string;
+    channel: string;
+    channel_address: string;
+    created_at: string;
+}
+export declare class NetworkError extends Error {
+    readonly status?: number | undefined;
+    readonly response?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, response?: unknown | undefined);
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkError = void 0;
+class NetworkError extends Error {
+    constructor(message, status, response) {
+        super(message);
+        this.status = status;
+        this.response = response;
+        this.name = 'NetworkError';
+    }
+}
+exports.NetworkError = NetworkError;

package/index.ts

@@ -0,0 +1,28 @@
+import { SubscriptionClient } from './client'
+
+import type { SubscriptionClientConfig } from './types'
+
+export { SubscriptionClient }
+export {
+  subscribeMessage,
+  unsubscribeMessage,
+  listSubscriptionsMessage,
+} from './message'
+export { NetworkError } from './types'
+export type {
+  Logger,
+  SubscriptionClientConfig,
+  SubscribeRequest,
+  SubscribeResponse,
+  UnsubscribeRequest,
+  UnsubscribeResponse,
+  ListSubscriptionsQuery,
+  ListSubscriptionsAuth,
+  Subscription,
+} from './types'
+
+export function createSubscriptionClient(
+  config: SubscriptionClientConfig,
+): SubscriptionClient {
+  return new SubscriptionClient(config)
+}

package/jest.config.js

@@ -0,0 +1,10 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+
+module.exports = {
+  preset: 'ts-jest',
+  rootDir: '.',
+  testRegex: '.*\\.test\\.ts$',
+  testEnvironment: 'node',
+  modulePathIgnorePatterns: ['dist/'],
+  testTimeout: 10000,
+}

package/message.ts

@@ -0,0 +1,25 @@
+/** Builds the signed message string for subscribe operations */
+export function subscribeMessage(
+  notificationType: string,
+  channel: string,
+  timestampSeconds: number,
+): string {
+  return `Subscribe ${notificationType} ${channel} ${timestampSeconds}`
+}
+
+/** Builds the signed message string for unsubscribe operations */
+export function unsubscribeMessage(
+  notificationType: string,
+  channel: string,
+  timestampSeconds: number,
+): string {
+  return `Unsubscribe ${notificationType} ${channel} ${timestampSeconds}`
+}
+
+/** Builds the signed message string for listing subscriptions */
+export function listSubscriptionsMessage(
+  pubkey: string,
+  timestampSeconds: number,
+): string {
+  return `ListSubscriptions ${pubkey} ${timestampSeconds}`
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@marinade.finance/ts-subscription-client",
+  "version": "1.0.0",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "jest",
+    "clean": "rm -rf dist .tsbuildinfo"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true
+  },
+  "include": ["./**/*.ts"],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.e2e.ts",
+    "**/__tests__"
+  ]
+}

package/types.ts

@@ -0,0 +1,81 @@
+/** Minimal logger interface — compatible with pino, console, etc. */
+export interface Logger {
+  debug(msg: string): void
+}
+
+/** Configuration for the subscription client */
+export interface SubscriptionClientConfig {
+  base_url: string
+  timeout_ms?: number
+  logger?: Logger
+}
+
+/** POST /subscriptions request */
+export interface SubscribeRequest {
+  pubkey: string
+  notification_type: string
+  channel: string
+  channel_address: string
+  signature: string
+  message: string
+  additional_data?: Record<string, unknown>
+}
+
+/** DELETE /subscriptions request */
+export interface UnsubscribeRequest {
+  pubkey: string
+  notification_type: string
+  channel: string
+  channel_address?: string
+  signature: string
+  message: string
+  additional_data?: Record<string, unknown>
+}
+
+/** GET /subscriptions auth */
+export interface ListSubscriptionsAuth {
+  signature: string
+  message: string
+}
+
+/** GET /subscriptions query */
+export interface ListSubscriptionsQuery {
+  pubkey: string
+  notification_type?: string
+}
+
+/** POST /subscriptions response */
+export interface SubscribeResponse {
+  user_id: string
+  notification_type: string
+  channel: string
+  channel_address: string
+  created_at: string
+  deep_link?: string
+  telegram_status?: 'already_activated' | 'bot_not_configured'
+}
+
+/** DELETE /subscriptions response */
+export interface UnsubscribeResponse {
+  deleted: boolean
+}
+
+/** GET /subscriptions response item */
+export interface Subscription {
+  user_id: string
+  notification_type: string
+  channel: string
+  channel_address: string
+  created_at: string
+}
+
+export class NetworkError extends Error {
+  constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly response?: unknown,
+  ) {
+    super(message)
+    this.name = 'NetworkError'
+  }
+}