@marinade.finance/ts-subscription-client 1.0.0 → 1.0.1

package/README.md

@@ -33,25 +33,20 @@ binds a user to a channel + address pair.
 
 ### telegram
 
-Telegram subscriptions use a two-phase activation flow:
+Telegram subscriptions use a deep-link 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.
+   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 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.
+   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.
 
-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.
+The `telegram_status` field tracks delivery state:
+`pending` → `active` → `inactive` / `unsubscribed` / `blocked`
 
 ### api
 
@@ -61,12 +56,12 @@ No activation step is needed — subscribing is sufficient.
 
 ## Notification types
 
-### bonds
+### sam_auction
 
-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.
+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:
 
@@ -80,3 +75,33 @@ The `additional_data` field for subscribe/unsubscribe should include:
 
 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

@@ -63,7 +63,7 @@ describe('SubscriptionClient E2E', () => {
           res.end(
             JSON.stringify({
               user_id: 'u1',
-              notification_type: 'bonds',
+              notification_type: 'sam_auction',
               channel: 'telegram',
               channel_address: '@test',
               created_at: '2024-01-01',
@@ -75,22 +75,22 @@ describe('SubscriptionClient E2E', () => {
 
       const result = await client.subscribe({
         pubkey: 'pk1',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         channel_address: '@test',
         signature: 'sig1',
-        message: 'Subscribe bonds telegram 1710000000',
+        message: 'Subscribe sam_auction telegram 1710000000',
         additional_data: { vote_account: 'va1' },
       })
 
       expect(receivedMethod).toBe('POST')
       expect(receivedBody).toEqual({
         pubkey: 'pk1',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         channel_address: '@test',
         signature: 'sig1',
-        message: 'Subscribe bonds telegram 1710000000',
+        message: 'Subscribe sam_auction telegram 1710000000',
         additional_data: { vote_account: 'va1' },
       })
       expect(result.deep_link).toBe('https://t.me/bot?start=abc')
@@ -114,10 +114,10 @@ describe('SubscriptionClient E2E', () => {
 
       const result = await client.unsubscribe({
         pubkey: 'pk1',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         signature: 'sig1',
-        message: 'Unsubscribe bonds telegram 1710000000',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
       })
 
       expect(receivedMethod).toBe('DELETE')
@@ -138,11 +138,11 @@ describe('SubscriptionClient E2E', () => {
 
       await client.unsubscribe({
         pubkey: 'pk1',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         channel_address: '@testuser',
         signature: 'sig1',
-        message: 'Unsubscribe bonds telegram 1710000000',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
       })
 
       expect(receivedBody?.channel_address).toBe('@testuser')
@@ -165,7 +165,7 @@ describe('SubscriptionClient E2E', () => {
           JSON.stringify([
             {
               user_id: 'u1',
-              notification_type: 'bonds',
+              notification_type: 'sam_auction',
               channel: 'telegram',
               channel_address: '@test',
               created_at: '2024-01-01',
@@ -177,7 +177,7 @@ describe('SubscriptionClient E2E', () => {
       const result = await client.listSubscriptions(
         {
           pubkey: 'pk1',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
         },
         {
           signature: 'sig1',
@@ -186,7 +186,7 @@ describe('SubscriptionClient E2E', () => {
       )
 
       expect(receivedUrl).toBe(
-        '/subscriptions?pubkey=pk1&notification_type=bonds',
+        '/subscriptions?pubkey=pk1&notification_type=sam_auction',
       )
       expect(receivedHeaders).toEqual({
         'x-solana-signature': 'sig1',
@@ -209,7 +209,7 @@ describe('SubscriptionClient E2E', () => {
         const error = await client
           .subscribe({
             pubkey: 'p',
-            notification_type: 'bonds',
+            notification_type: 'sam_auction',
             channel: 'telegram',
             channel_address: '@t',
             signature: 's',
@@ -233,7 +233,7 @@ describe('SubscriptionClient E2E', () => {
       await expect(
         unreachableClient.subscribe({
           pubkey: 'p',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
           channel: 'telegram',
           channel_address: '@t',
           signature: 's',

package/__tests__/client.test.ts

@@ -16,7 +16,7 @@ describe('SubscriptionClient', () => {
       const mockFetch = global.fetch as jest.Mock
       const responseBody = {
         user_id: 'user-1',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         channel_address: '@testuser',
         created_at: '2024-01-01T00:00:00Z',
@@ -33,11 +33,11 @@ describe('SubscriptionClient', () => {
 
       const request = {
         pubkey: 'pubkey123',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         channel_address: '@testuser',
         signature: 'sig123',
-        message: 'Subscribe bonds telegram 1710000000',
+        message: 'Subscribe sam_auction telegram 1710000000',
         additional_data: { vote_account: 'vote123' },
       }
 
@@ -68,7 +68,7 @@ describe('SubscriptionClient', () => {
       await expect(
         client.subscribe({
           pubkey: 'p',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
           channel: 'telegram',
           channel_address: '@test',
           signature: 's',
@@ -88,7 +88,7 @@ describe('SubscriptionClient', () => {
       await expect(
         client.subscribe({
           pubkey: 'p',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
           channel: 'telegram',
           channel_address: '@test',
           signature: 's',
@@ -112,10 +112,10 @@ describe('SubscriptionClient', () => {
 
       const request = {
         pubkey: 'pubkey123',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         signature: 'sig123',
-        message: 'Unsubscribe bonds telegram 1710000000',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
       }
 
       const result = await client.unsubscribe(request)
@@ -140,11 +140,11 @@ describe('SubscriptionClient', () => {
 
       const request = {
         pubkey: 'pubkey123',
-        notification_type: 'bonds',
+        notification_type: 'sam_auction',
         channel: 'telegram',
         channel_address: '@testuser',
         signature: 'sig123',
-        message: 'Unsubscribe bonds telegram 1710000000',
+        message: 'Unsubscribe sam_auction telegram 1710000000',
       }
 
       await client.unsubscribe(request)
@@ -170,7 +170,7 @@ describe('SubscriptionClient', () => {
       await expect(
         client.unsubscribe({
           pubkey: 'p',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
           channel: 'telegram',
           signature: 's',
           message: 'm',
@@ -185,7 +185,7 @@ describe('SubscriptionClient', () => {
       const responseBody = [
         {
           user_id: 'user-1',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
           channel: 'telegram',
           channel_address: '@testuser',
           created_at: '2024-01-01T00:00:00Z',
@@ -203,7 +203,7 @@ describe('SubscriptionClient', () => {
       const result = await client.listSubscriptions(
         {
           pubkey: 'pubkey123',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
         },
         {
           signature: 'sig123',
@@ -215,7 +215,7 @@ describe('SubscriptionClient', () => {
       expect(mockFetch).toHaveBeenCalledTimes(1)
       const [url, options] = mockFetch.mock.calls[0]
       expect(url).toBe(
-        'http://localhost:3000/subscriptions?pubkey=pubkey123&notification_type=bonds',
+        'http://localhost:3000/subscriptions?pubkey=pubkey123&notification_type=sam_auction',
       )
       expect(options?.method).toBe('GET')
       expect(options?.headers).toEqual({
@@ -224,6 +224,54 @@ describe('SubscriptionClient', () => {
       })
     })
 
+    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({
@@ -288,7 +336,7 @@ describe('SubscriptionClient', () => {
       await expect(
         client.subscribe({
           pubkey: 'p',
-          notification_type: 'bonds',
+          notification_type: 'sam_auction',
           channel: 'telegram',
           channel_address: '@test',
           signature: 's',

package/__tests__/message.test.ts

@@ -6,14 +6,14 @@ import {
 
 describe('message helpers', () => {
   it('subscribeMessage', () => {
-    expect(subscribeMessage('bonds', 'telegram', 1710000000)).toBe(
-      'Subscribe bonds telegram 1710000000',
+    expect(subscribeMessage('sam_auction', 'telegram', 1710000000)).toBe(
+      'Subscribe sam_auction telegram 1710000000',
     )
   })
 
   it('unsubscribeMessage', () => {
-    expect(unsubscribeMessage('bonds', 'email', 1710000000)).toBe(
-      'Unsubscribe bonds email 1710000000',
+    expect(unsubscribeMessage('sam_auction', 'email', 1710000000)).toBe(
+      'Unsubscribe sam_auction email 1710000000',
     )
   })
 

package/client.ts

@@ -61,6 +61,12 @@ export class SubscriptionClient {
     if (query.notification_type) {
       params.set('notification_type', query.notification_type)
     }
+    if (
+      query.additional_data &&
+      Object.keys(query.additional_data).length > 0
+    ) {
+      params.set('additional_data', JSON.stringify(query.additional_data))
+    }
     const path = `${PATH_SUBSCRIPTIONS}?${params.toString()}`
 
     this.logger?.debug(`GET ${path} signature: [redacted]`)

package/dist/client.js

@@ -37,6 +37,10 @@ class SubscriptionClient {
         if (query.notification_type) {
             params.set('notification_type', query.notification_type);
         }
+        if (query.additional_data &&
+            Object.keys(query.additional_data).length > 0) {
+            params.set('additional_data', JSON.stringify(query.additional_data));
+        }
         const path = `${PATH_SUBSCRIPTIONS}?${params.toString()}`;
         this.logger?.debug(`GET ${path} signature: [redacted]`);
         return this.fetch(path, {

package/dist/index.d.ts

@@ -4,4 +4,5 @@ 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 const NOTIFICATION_TYPE_SAM_AUCTION = "sam_auction";
 export declare function createSubscriptionClient(config: SubscriptionClientConfig): SubscriptionClient;

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NetworkError = exports.listSubscriptionsMessage = exports.unsubscribeMessage = exports.subscribeMessage = exports.SubscriptionClient = void 0;
+exports.NOTIFICATION_TYPE_SAM_AUCTION = 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; } });
@@ -10,6 +10,7 @@ Object.defineProperty(exports, "unsubscribeMessage", { enumerable: true, get: fu
 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; } });
+exports.NOTIFICATION_TYPE_SAM_AUCTION = 'sam_auction';
 function createSubscriptionClient(config) {
     return new client_1.SubscriptionClient(config);
 }

package/dist/types.d.ts

@@ -37,6 +37,7 @@ export interface ListSubscriptionsAuth {
 export interface ListSubscriptionsQuery {
     pubkey: string;
     notification_type?: string;
+    additional_data?: Record<string, unknown>;
 }
 /** POST /subscriptions response */
 export interface SubscribeResponse {
@@ -46,7 +47,7 @@ export interface SubscribeResponse {
     channel_address: string;
     created_at: string;
     deep_link?: string;
-    telegram_status?: 'already_activated' | 'bot_not_configured';
+    telegram_status?: 'pending' | 'active' | 'inactive' | 'unsubscribed' | 'blocked' | 'already_activated' | 'bot_not_configured';
 }
 /** DELETE /subscriptions response */
 export interface UnsubscribeResponse {
@@ -59,6 +60,7 @@ export interface Subscription {
     channel: string;
     channel_address: string;
     created_at: string;
+    telegram_status?: 'pending' | 'active' | 'inactive' | 'unsubscribed' | 'blocked';
 }
 export declare class NetworkError extends Error {
     readonly status?: number | undefined;

package/index.ts

@@ -21,6 +21,8 @@ export type {
   Subscription,
 } from './types'
 
+export const NOTIFICATION_TYPE_SAM_AUCTION = 'sam_auction'
+
 export function createSubscriptionClient(
   config: SubscriptionClientConfig,
 ): SubscriptionClient {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marinade.finance/ts-subscription-client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/types.ts

@@ -42,6 +42,7 @@ export interface ListSubscriptionsAuth {
 export interface ListSubscriptionsQuery {
   pubkey: string
   notification_type?: string
+  additional_data?: Record<string, unknown>
 }
 
 /** POST /subscriptions response */
@@ -52,7 +53,14 @@ export interface SubscribeResponse {
   channel_address: string
   created_at: string
   deep_link?: string
-  telegram_status?: 'already_activated' | 'bot_not_configured'
+  telegram_status?:
+    | 'pending'
+    | 'active'
+    | 'inactive'
+    | 'unsubscribed'
+    | 'blocked'
+    | 'already_activated'
+    | 'bot_not_configured'
 }
 
 /** DELETE /subscriptions response */
@@ -67,6 +75,12 @@ export interface Subscription {
   channel: string
   channel_address: string
   created_at: string
+  telegram_status?:
+    | 'pending'
+    | 'active'
+    | 'inactive'
+    | 'unsubscribed'
+    | 'blocked'
 }
 
 export class NetworkError extends Error {