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

package/__tests__/message.test.ts

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

package/client.ts

@@ -0,0 +1,158 @@
+import {
+  type SubscriptionClientConfig,
+  type Logger,
+  type SubscribeRequest,
+  type SubscribeResponse,
+  type UnsubscribeRequest,
+  type UnsubscribeResponse,
+  type ListSubscriptionsQuery,
+  type ListSubscriptionsAuth,
+  type Subscription,
+  type ListNotificationsQuery,
+  type Notification,
+  NetworkError,
+} from './types'
+
+const PATH_SUBSCRIPTIONS = '/subscriptions'
+const PATH_NOTIFICATIONS = '/notifications'
+
+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)
+    }
+    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<Subscription[]>(path, {
+      method: 'GET',
+      headers: {
+        'x-solana-signature': auth.signature,
+        'x-solana-message': auth.message,
+      },
+    })
+  }
+
+  async listNotifications(
+    query: ListNotificationsQuery,
+  ): Promise<Notification[]> {
+    const params = new URLSearchParams()
+    params.set('user_id', query.user_id)
+    if (query.notification_type) {
+      params.set('notification_type', query.notification_type)
+    }
+    if (query.priority) {
+      params.set('priority', query.priority)
+    }
+    if (query.inner_type) {
+      params.set('inner_type', query.inner_type)
+    }
+    if (query.limit !== undefined) {
+      params.set('limit', query.limit.toString())
+    }
+    if (query.offset !== undefined) {
+      params.set('offset', query.offset.toString())
+    }
+    const path = `${PATH_NOTIFICATIONS}?${params.toString()}`
+
+    this.logger?.debug(`GET ${path}`)
+    return this.fetch<Notification[]>(path, {
+      method: 'GET',
+    })
+  }
+
+  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,12 @@
+import { type SubscriptionClientConfig, type SubscribeRequest, type SubscribeResponse, type UnsubscribeRequest, type UnsubscribeResponse, type ListSubscriptionsQuery, type ListSubscriptionsAuth, type Subscription, type ListNotificationsQuery, type Notification } 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[]>;
+    listNotifications(query: ListNotificationsQuery): Promise<Notification[]>;
+    private fetch;
+}

package/dist/client.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionClient = void 0;
+const types_1 = require("./types");
+const PATH_SUBSCRIPTIONS = '/subscriptions';
+const PATH_NOTIFICATIONS = '/notifications';
+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);
+        }
+        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, {
+            method: 'GET',
+            headers: {
+                'x-solana-signature': auth.signature,
+                'x-solana-message': auth.message,
+            },
+        });
+    }
+    async listNotifications(query) {
+        const params = new URLSearchParams();
+        params.set('user_id', query.user_id);
+        if (query.notification_type) {
+            params.set('notification_type', query.notification_type);
+        }
+        if (query.priority) {
+            params.set('priority', query.priority);
+        }
+        if (query.inner_type) {
+            params.set('inner_type', query.inner_type);
+        }
+        if (query.limit !== undefined) {
+            params.set('limit', query.limit.toString());
+        }
+        if (query.offset !== undefined) {
+            params.set('offset', query.offset.toString());
+        }
+        const path = `${PATH_NOTIFICATIONS}?${params.toString()}`;
+        this.logger?.debug(`GET ${path}`);
+        return this.fetch(path, {
+            method: 'GET',
+        });
+    }
+    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,8 @@
+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, ListNotificationsQuery, Notification, } from './types';
+export declare const NOTIFICATION_TYPE_SAM_AUCTION = "sam_auction";
+export declare function createSubscriptionClient(config: SubscriptionClientConfig): SubscriptionClient;

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });
+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; } });
+exports.NOTIFICATION_TYPE_SAM_AUCTION = 'sam_auction';
+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,91 @@
+/** 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;
+    additional_data?: Record<string, unknown>;
+}
+/** 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?: 'pending' | 'active' | 'inactive' | 'unsubscribed' | 'blocked' | '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;
+    telegram_status?: 'pending' | 'active' | 'inactive' | 'unsubscribed' | 'blocked';
+}
+/** GET /notifications query (public, no auth required) */
+export interface ListNotificationsQuery {
+    user_id: string;
+    notification_type?: string;
+    priority?: string;
+    inner_type?: string;
+    limit?: number;
+    offset?: number;
+}
+/** GET /notifications response item */
+export interface Notification {
+    id: number;
+    notification_type: string;
+    inner_type: string;
+    user_id: string;
+    priority: string;
+    message: string;
+    data: Record<string, unknown>;
+    notification_id: string | null;
+    relevance_until: 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,32 @@
+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,
+  ListNotificationsQuery,
+  Notification,
+} from './types'
+
+export const NOTIFICATION_TYPE_SAM_AUCTION = 'sam_auction'
+
+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-beta.1",
+  "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__"
+  ]
+}