@cored-im/openapi-sdk 0.28.102

package/src/core/api_client.ts

@@ -0,0 +1,344 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Config } from './config';
+import type {
+  ApiClient,
+  ApiRequest,
+  ApiResponse,
+  EventHeader,
+  WrappedEventHandler,
+} from './types';
+import { USER_AGENT } from './version';
+import {
+  DEFAULT_PING_PATH,
+  DEFAULT_TOKEN_PATH,
+  DEFAULT_GATEWAY_PATH,
+} from './consts';
+import { CryptoManager, sha256Hex } from './crypto';
+import { WsClient } from './ws_client';
+import {
+  encodeSecureMessage,
+  decodeSecureMessage,
+  encodeHttpRequest,
+  decodeHttpResponse,
+} from '@/internal/transport';
+import type { HttpRequest } from '@/internal/transport';
+
+const TIMESTAMP_HEADER = 'X-Cored-Timestamp';
+const NONCE_HEADER = 'X-Cored-Nonce';
+
+export class DefaultApiClient implements ApiClient {
+  private config: Config;
+  private secret: string = '';
+  private token: string = '';
+  private tokenRefreshAt: number = 0;
+  private tokenExpiresAt: number = 0;
+  private tokenFetching: boolean = false;
+  private tokenPromise: Promise<void> | null = null;
+  private pingCalled: boolean = false;
+  private pingExpiresAt: number = 0;
+  private pingFetching: boolean = false;
+  private pingPromise: Promise<void> | null = null;
+  private cryptoManager: CryptoManager;
+  private ws: WsClient;
+
+  constructor(config: Config) {
+    this.config = config;
+    this.cryptoManager = new CryptoManager(config);
+    this.ws = new WsClient({
+      config,
+      getSecret: () => this.secret,
+      getToken: () => this.getToken(),
+      ensurePing: () => this.ensurePing(),
+      cryptoManager: this.cryptoManager,
+    });
+  }
+
+  async init(): Promise<void> {
+    this.secret = await sha256Hex(`${this.config.appId}:${this.config.appSecret}`);
+  }
+
+  async preheat(): Promise<void> {
+    await this.ensurePing();
+    await this.getToken();
+  }
+
+  async close(): Promise<void> {
+    this.ws.close();
+  }
+
+  onEvent(eventType: string, handler: WrappedEventHandler): void {
+    this.ws.onEvent(eventType, handler);
+  }
+
+  offEvent(eventType: string, handler: WrappedEventHandler): void {
+    this.ws.offEvent(eventType, handler);
+  }
+
+  async request(req: ApiRequest): Promise<ApiResponse> {
+    await this.ensurePing();
+
+    // Build URL
+    let path = req.path;
+    if (req.pathParams) {
+      for (const [key, value] of Object.entries(req.pathParams)) {
+        path = path.replace(`:${key}`, encodeURIComponent(value));
+      }
+    }
+
+    let url = this.config.backendUrl + path;
+    if (req.queryParams) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(req.queryParams)) {
+        if (value) params.set(key, value);
+      }
+      const qs = params.toString();
+      if (qs) url += '?' + qs;
+    }
+
+    // Encrypted path
+    if (this.config.enableEncryption && req.withAppAccessToken) {
+      const token = await this.getToken();
+      const bodyBytes = req.body
+        ? new TextEncoder().encode(this.config.jsonMarshal(req.body))
+        : new Uint8Array(0);
+
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+        'User-Agent': USER_AGENT,
+        [TIMESTAMP_HEADER]: String(this.config.timeManager.getServerTimestamp()),
+        [NONCE_HEADER]: randomAlphanumeric(16),
+      };
+      if (req.headerParams) {
+        Object.assign(headers, req.headerParams);
+      }
+
+      const httpReq: HttpRequest = {
+        method: req.method,
+        path: url.replace(this.config.backendUrl, ''),
+        headers,
+        body: bodyBytes,
+        reqId: '',
+      };
+
+      // WebSocket path
+      if (req.withWebSocket) {
+        const httpResp = await this.ws.httpRequest(httpReq);
+        return {
+          json: async () => JSON.parse(new TextDecoder().decode(httpResp.body)),
+          body: async () => httpResp.body instanceof Uint8Array ? httpResp.body : new Uint8Array(httpResp.body),
+        };
+      }
+
+      // Gateway path
+      const httpReqBytes = encodeHttpRequest(httpReq);
+      const secureMessage = await this.cryptoManager.encryptMessage(this.secret, httpReqBytes);
+      const secureBytes = encodeSecureMessage(secureMessage);
+
+      const gatewayUrl = this.config.backendUrl + DEFAULT_GATEWAY_PATH;
+      const resp = await this.config.httpClient.fetch(gatewayUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-protobuf',
+          'Authorization': `Bearer ${token}`,
+          'User-Agent': USER_AGENT,
+        },
+        body: secureBytes as unknown as BodyInit,
+      });
+
+      const respBytes = new Uint8Array(await resp.arrayBuffer());
+      const respSecureMessage = decodeSecureMessage(respBytes);
+      const decryptedBytes = await this.cryptoManager.decryptMessage(this.secret, respSecureMessage);
+      const httpResp = decodeHttpResponse(decryptedBytes);
+
+      return {
+        json: async () => JSON.parse(new TextDecoder().decode(httpResp.body)),
+        body: async () => httpResp.body instanceof Uint8Array ? httpResp.body : new Uint8Array(httpResp.body),
+      };
+    }
+
+    // Plain HTTP path
+    const timestamp = String(this.config.timeManager.getServerTimestamp());
+    const nonce = randomAlphanumeric(16);
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'User-Agent': USER_AGENT,
+      [TIMESTAMP_HEADER]: timestamp,
+      [NONCE_HEADER]: nonce,
+    };
+
+    if (req.withAppAccessToken) {
+      const token = await this.getToken();
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+    if (req.headerParams) {
+      for (const [key, value] of Object.entries(req.headerParams)) {
+        if (value) headers[key] = value;
+      }
+    }
+
+    const fetchInit: RequestInit = {
+      method: req.method,
+      headers,
+    };
+    if (req.body && req.method !== 'GET') {
+      fetchInit.body = this.config.jsonMarshal(req.body);
+    }
+
+    const resp = await this.config.httpClient.fetch(url, fetchInit);
+    return {
+      json: async () => resp.json(),
+      body: async () => new Uint8Array(await resp.arrayBuffer()),
+    };
+  }
+
+  // --- Token management ---
+
+  private async getToken(): Promise<string> {
+    const now = this.config.timeManager.getServerTimestamp();
+
+    // Token still fully valid
+    if (this.token && this.tokenRefreshAt > now) {
+      return this.token;
+    }
+
+    // Token expired
+    if (!this.token || this.tokenExpiresAt <= now) {
+      if (this.tokenPromise) {
+        await this.tokenPromise;
+        return this.token;
+      }
+      this.tokenPromise = this.fetchToken();
+      try {
+        await this.tokenPromise;
+      } finally {
+        this.tokenPromise = null;
+      }
+      return this.token;
+    }
+
+    // Token near expiry, refresh in background
+    if (!this.tokenFetching) {
+      this.tokenFetching = true;
+      this.fetchToken().finally(() => {
+        this.tokenFetching = false;
+      });
+    }
+
+    return this.token;
+  }
+
+  private async fetchToken(): Promise<void> {
+    const timestamp = String(this.config.timeManager.getServerTimestamp());
+    const nonce = randomAlphanumeric(16);
+    const signPayload = `${this.config.appId}:${timestamp}:${this.config.appSecret}:${nonce}`;
+    const signature = await sha256Hex(signPayload);
+
+    const url = this.config.backendUrl + DEFAULT_TOKEN_PATH;
+    const resp = await this.config.httpClient.fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': USER_AGENT,
+      },
+      body: JSON.stringify({
+        app_id: this.config.appId,
+        timestamp,
+        nonce,
+        signature: `v1:${signature}`,
+      }),
+    });
+
+    const data = await resp.json() as {
+      code: number;
+      msg: string;
+      data?: {
+        access_token: string;
+        expires_in: number;
+      };
+    };
+
+    if (data.code !== 0 || !data.data) {
+      throw new Error(`fetch token failed: code=${data.code}, msg=${data.msg}`);
+    }
+
+    this.token = data.data.access_token;
+    const now = this.config.timeManager.getServerTimestamp();
+    this.tokenExpiresAt = now + (data.data.expires_in - 60) * 1000;
+    this.tokenRefreshAt = this.tokenExpiresAt - 5 * 60 * 1000;
+  }
+
+  // --- Ping / server time sync ---
+
+  private async ensurePing(): Promise<void> {
+    const now = Date.now();
+
+    if (this.pingCalled && this.pingExpiresAt > now) {
+      return;
+    }
+
+    if (!this.pingCalled || this.pingExpiresAt <= now) {
+      if (this.pingPromise) {
+        await this.pingPromise;
+        return;
+      }
+      this.pingPromise = this.fetchPing();
+      try {
+        await this.pingPromise;
+      } finally {
+        this.pingPromise = null;
+      }
+      return;
+    }
+
+    // Background refresh
+    if (!this.pingFetching) {
+      this.pingFetching = true;
+      this.fetchPing().finally(() => {
+        this.pingFetching = false;
+      });
+    }
+  }
+
+  private async fetchPing(): Promise<void> {
+    const url = this.config.backendUrl + DEFAULT_PING_PATH;
+    const resp = await this.config.httpClient.fetch(url, {
+      method: 'GET',
+      headers: { 'User-Agent': USER_AGENT },
+    });
+
+    const data = await resp.json() as {
+      code: number;
+      msg: string;
+      data?: {
+        version: string;
+        timestamp: number;
+        org_code: string;
+      };
+    };
+
+    if (data.code !== 0 || !data.data) {
+      throw new Error(`ping failed: code=${data.code}, msg=${data.msg}`);
+    }
+
+    this.config.timeManager.syncServerTimestamp(data.data.timestamp);
+    this.pingCalled = true;
+    this.pingExpiresAt = Date.now() + 10 * 60 * 1000; // 10 minutes
+    this.config.logger.info(`ping ok, server version=${data.data.version}, org_code=${data.data.org_code}`);
+  }
+}
+
+// --- Helpers ---
+
+const ALPHANUMERIC = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+function randomAlphanumeric(size: number): string {
+  const bytes = new Uint8Array(size);
+  crypto.getRandomValues(bytes);
+  let result = '';
+  for (let i = 0; i < size; i++) {
+    result += ALPHANUMERIC[bytes[i] % 62];
+  }
+  return result;
+}

package/src/core/config.ts

@@ -0,0 +1,25 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+  ApiClient,
+  HttpClient,
+  Logger,
+  TimeManager,
+  Marshaller,
+  Unmarshaller,
+} from './types';
+
+export interface Config {
+  appId: string;
+  appSecret: string;
+  backendUrl: string;
+  httpClient: HttpClient;
+  apiClient: ApiClient;
+  enableEncryption: boolean;
+  requestTimeout: number;
+  timeManager: TimeManager;
+  logger: Logger;
+  jsonMarshal: Marshaller;
+  jsonUnmarshal: Unmarshaller;
+}

package/src/core/consts.ts

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+export const DEFAULT_PING_PATH = '/oapi/stat/v1/ping';
+export const DEFAULT_TOKEN_PATH = '/oapi/auth/v1/app/token';
+export const DEFAULT_GATEWAY_PATH = '/oapi/transport/v1/gateway';
+export const DEFAULT_WS_PATH = '/oapi/transport/v1/ws';
+export const DEFAULT_SECURE_VERSION = '1.0';

package/src/core/crypto.ts

@@ -0,0 +1,212 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Config } from './config';
+import type { SecureMessage } from '@/internal/transport';
+import { DEFAULT_SECURE_VERSION } from './consts';
+
+const ALPHANUMERIC = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+export class CryptoManager {
+  private config: Config;
+  private prefix: string;
+  private counter: number[] = [0, 0, 0, 0, 0];
+
+  constructor(config: Config) {
+    this.config = config;
+    this.prefix = randomAlphanumeric(6);
+  }
+
+  async encryptMessage(secret: string, data: Uint8Array): Promise<SecureMessage> {
+    const timestamp = this.config.timeManager.getServerTimestamp();
+    const nonce = this.getNonce();
+
+    // Derive initKey = SHA256(timestamp:secret:nonce)
+    const initKey = await sha256Bytes(`${timestamp}:${secret}:${nonce}`);
+
+    // Generate random AES key
+    const aesKey = randomBytes(32);
+
+    // Compress data with gzip
+    const compressed = await compressGzip(data);
+
+    // Encrypt AES key with initKey
+    const encryptedKey = await encryptAES256CBC(aesKey, initKey);
+
+    // Encrypt compressed data with AES key
+    const encryptedData = await encryptAES256CBC(compressed, aesKey);
+
+    return {
+      version: DEFAULT_SECURE_VERSION,
+      timestamp,
+      nonce,
+      encryptedKey,
+      encryptedData,
+    };
+  }
+
+  async decryptMessage(secret: string, message: SecureMessage): Promise<Uint8Array> {
+    if (message.version !== DEFAULT_SECURE_VERSION) {
+      throw new Error(`unsupported secure message version: ${message.version}`);
+    }
+
+    // Derive initKey
+    const initKey = await sha256Bytes(`${message.timestamp}:${secret}:${message.nonce}`);
+
+    // Decrypt AES key
+    const aesKey = await decryptAES256CBC(message.encryptedKey, initKey);
+
+    // Decrypt data
+    const compressed = await decryptAES256CBC(message.encryptedData, aesKey);
+
+    // Decompress
+    return await decompressGzip(compressed);
+  }
+
+  private getNonce(): string {
+    const random = randomAlphanumeric(5);
+    const counter = this.formatCounter();
+    this.addCounter();
+    return this.prefix + random + counter;
+  }
+
+  private formatCounter(): string {
+    let result = '';
+    for (let i = 0; i < 5; i++) {
+      result += ALPHANUMERIC[this.counter[i]];
+    }
+    return result;
+  }
+
+  private addCounter(): void {
+    for (let i = 4; i >= 0; i--) {
+      this.counter[i]++;
+      if (this.counter[i] < 62) {
+        break;
+      }
+      this.counter[i] = 0;
+    }
+  }
+}
+
+// --- Crypto helpers using Web Crypto API ---
+
+async function sha256Bytes(input: string): Promise<Uint8Array> {
+  const data = new TextEncoder().encode(input);
+  const hash = await crypto.subtle.digest('SHA-256', data);
+  return new Uint8Array(hash);
+}
+
+export async function sha256Hex(input: string): Promise<string> {
+  const bytes = await sha256Bytes(input);
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+async function encryptAES256CBC(data: Uint8Array, key: Uint8Array): Promise<Uint8Array> {
+  const padded = pkcs7Pad(data);
+  const iv = randomBytes(16);
+  const cryptoKey = await crypto.subtle.importKey('raw', toBuffer(key), { name: 'AES-CBC' }, false, ['encrypt']);
+  const encrypted = await crypto.subtle.encrypt({ name: 'AES-CBC', iv: toBuffer(iv) }, cryptoKey, toBuffer(padded));
+  // Return IV + ciphertext
+  const result = new Uint8Array(iv.length + encrypted.byteLength);
+  result.set(iv, 0);
+  result.set(new Uint8Array(encrypted), iv.length);
+  return result;
+}
+
+async function decryptAES256CBC(data: Uint8Array, key: Uint8Array): Promise<Uint8Array> {
+  if (data.length < 16 || data.length % 16 !== 0) {
+    throw new Error('invalid encrypted data length');
+  }
+  const iv = data.slice(0, 16);
+  const ciphertext = data.slice(16);
+  const cryptoKey = await crypto.subtle.importKey('raw', toBuffer(key), { name: 'AES-CBC' }, false, ['decrypt']);
+  // Web Crypto API handles PKCS7 unpadding automatically for AES-CBC
+  const decrypted = await crypto.subtle.decrypt({ name: 'AES-CBC', iv: toBuffer(iv) }, cryptoKey, toBuffer(ciphertext));
+  return new Uint8Array(decrypted);
+}
+
+function pkcs7Pad(data: Uint8Array): Uint8Array {
+  const blockSize = 16;
+  const padding = blockSize - (data.length % blockSize);
+  const padded = new Uint8Array(data.length + padding);
+  padded.set(data);
+  padded.fill(padding, data.length);
+  return padded;
+}
+
+// --- Compression ---
+
+async function compressGzip(data: Uint8Array): Promise<Uint8Array> {
+  if (typeof CompressionStream !== 'undefined') {
+    const stream = new CompressionStream('gzip');
+    const writer = stream.writable.getWriter();
+    void writer.write(toBuffer(data));
+    void writer.close();
+    const chunks: Uint8Array[] = [];
+    const reader = stream.readable.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+  throw new Error('CompressionStream not available. Please use a modern browser or Node.js 18+.');
+}
+
+async function decompressGzip(data: Uint8Array): Promise<Uint8Array> {
+  if (typeof DecompressionStream !== 'undefined') {
+    const stream = new DecompressionStream('gzip');
+    const writer = stream.writable.getWriter();
+    void writer.write(toBuffer(data));
+    void writer.close();
+    const chunks: Uint8Array[] = [];
+    const reader = stream.readable.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+  throw new Error('DecompressionStream not available. Please use a modern browser or Node.js 18+.');
+}
+
+// --- Buffer helpers ---
+
+/** Convert Uint8Array to ArrayBuffer (fixes TS 5.5+ BufferSource strictness). */
+function toBuffer(data: Uint8Array): ArrayBuffer {
+  return (data.buffer as ArrayBuffer).slice(data.byteOffset, data.byteOffset + data.byteLength);
+}
+
+// --- Random helpers ---
+
+function randomBytes(size: number): Uint8Array {
+  const bytes = new Uint8Array(size);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+function randomAlphanumeric(size: number): string {
+  const bytes = randomBytes(size);
+  let result = '';
+  for (let i = 0; i < size; i++) {
+    result += ALPHANUMERIC[bytes[i] % 62];
+  }
+  return result;
+}

package/src/core/http_client.ts

@@ -0,0 +1,25 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HttpClient } from './types';
+
+export class DefaultHttpClient implements HttpClient {
+  private timeout: number;
+
+  constructor(timeout: number = 60000) {
+    this.timeout = timeout;
+  }
+
+  async fetch(url: string, init: RequestInit): Promise<Response> {
+    if (this.timeout > 0) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        return await fetch(url, { ...init, signal: controller.signal });
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    return fetch(url, init);
+  }
+}

package/src/core/logger.ts

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import { LoggerLevel } from './types';
+import type { Logger } from './types';
+
+export class DefaultLogger implements Logger {
+  private level: LoggerLevel;
+
+  constructor(level: LoggerLevel = LoggerLevel.Info) {
+    this.level = level;
+  }
+
+  debug(msg: string, ...args: unknown[]): void {
+    if (this.level <= LoggerLevel.Debug) {
+      console.debug(`[sdk] DEBUG ${msg}`, ...args);
+    }
+  }
+
+  info(msg: string, ...args: unknown[]): void {
+    if (this.level <= LoggerLevel.Info) {
+      console.info(`[sdk] INFO ${msg}`, ...args);
+    }
+  }
+
+  warn(msg: string, ...args: unknown[]): void {
+    if (this.level <= LoggerLevel.Warn) {
+      console.warn(`[sdk] WARN ${msg}`, ...args);
+    }
+  }
+
+  error(msg: string, ...args: unknown[]): void {
+    if (this.level <= LoggerLevel.Error) {
+      console.error(`[sdk] ERROR ${msg}`, ...args);
+    }
+  }
+}

package/src/core/time_manager.ts

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Cored Limited
+// SPDX-License-Identifier: Apache-2.0
+
+import type { TimeManager } from './types';
+
+export class DefaultTimeManager implements TimeManager {
+  private serverTimeBase = 0;
+  private systemTimeBase = 0;
+
+  getSystemTimestamp(): number {
+    return Date.now();
+  }
+
+  getServerTimestamp(): number {
+    if (this.serverTimeBase === 0) {
+      return this.getSystemTimestamp();
+    }
+    return this.getSystemTimestamp() - this.systemTimeBase + this.serverTimeBase;
+  }
+
+  syncServerTimestamp(timestamp: number): void {
+    if (timestamp <= this.serverTimeBase) {
+      return;
+    }
+    this.serverTimeBase = timestamp;
+    this.systemTimeBase = this.getSystemTimestamp();
+  }
+}