@bitalcer/partner-api 1.0.0

package/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Bitalcer Partner API — TypeScript type definitions v1.0.0
+ */
+
+declare module '@bitalcer/partner-api' {
+  export interface ClientConfig {
+    apiKey: string;
+    hmacSecret: string;
+    baseUrl?: string;
+  }
+
+  export interface PingResponse {
+    status: string;
+    partner_id: number;
+    environment: string;
+  }
+
+  export interface UserResponse {
+    id: number;
+    partner_id: number;
+    external_user_id: string;
+    internal_user_id: number | null;
+    status: string;
+  }
+
+  export interface WalletResponse {
+    external_user_id: string;
+    address: string;
+    chain: string;
+  }
+
+  export interface BalanceResponse {
+    external_user_id: string;
+    token: string;
+    chain: string;
+    balance: string;
+    address: string;
+  }
+
+  export interface WithdrawParams {
+    externalUserId: string;
+    toAddress: string;
+    amount: string;
+    token?: string;
+    chain?: 'bsc' | 'polygon';
+  }
+
+  export interface WithdrawResponse {
+    withdraw_id: string;
+    tx_hash: string;
+    status: string;
+  }
+
+  export interface TransferParams {
+    senderExternalUserId: string;
+    receiverExternalUserId: string;
+    amount: string;
+    token?: string;
+  }
+
+  export interface TransferResponse {
+    transfer_id: string;
+    status: string;
+  }
+
+  export interface QuoteParams {
+    externalUserId: string;
+    baseAsset: 'GTQ' | 'USDT';
+    quoteAsset: 'GTQ' | 'USDT';
+    amount: number;
+  }
+
+  export interface QuoteResponse {
+    pair: string;
+    estimated_amount_out: number;
+    price_applied: number;
+    fee_amount: number;
+    fee_bps: number;
+  }
+
+  export interface CreateOrderParams {
+    externalUserId: string;
+    baseAsset: 'GTQ' | 'USDT';
+    quoteAsset: 'GTQ' | 'USDT';
+    requestedAmount: number;
+    side: 'buy' | 'sell';
+  }
+
+  export interface OrderResponse {
+    order_id: string;
+    status: string;
+    quote_expires_at: string;
+  }
+
+  export interface ExecuteResponse {
+    order_id: string;
+    status: string;
+    executed_at: string;
+  }
+
+  export interface OrderStatusResponse {
+    order_id: string;
+    status: string;
+    executed_amount: number;
+    price_applied: number;
+  }
+
+  export interface TreasuryBalanceResponse {
+    partner_id: number;
+    available_balance_usd: number;
+    reserved_balance_usd: number;
+    tier: string;
+  }
+
+  export interface ApiError extends Error {
+    status: number;
+    code: string;
+    body: any;
+  }
+
+  export class UsersClient {
+    create(externalUserId: string): Promise<UserResponse>;
+  }
+
+  export class WalletsClient {
+    create(externalUserId: string, chain?: 'bsc' | 'polygon' | 'btc'): Promise<WalletResponse>;
+    getBalance(externalUserId: string, opts?: { token?: string; chain?: string }): Promise<BalanceResponse>;
+    getAddress(externalUserId: string, opts?: { chain?: string }): Promise<WalletResponse>;
+  }
+
+  export class TransactionsClient {
+    withdraw(params: WithdrawParams): Promise<WithdrawResponse>;
+    transfer(params: TransferParams): Promise<TransferResponse>;
+  }
+
+  export class ConversionClient {
+    quote(params: QuoteParams): Promise<QuoteResponse>;
+    createOrder(params: CreateOrderParams): Promise<OrderResponse>;
+    execute(externalUserId: string, orderId: string): Promise<ExecuteResponse>;
+    getStatus(externalUserId: string, orderId: string): Promise<OrderStatusResponse>;
+  }
+
+  export class TreasuryClient {
+    getBalance(): Promise<TreasuryBalanceResponse>;
+  }
+
+  export class Client {
+    constructor(config: ClientConfig);
+    ping(): Promise<PingResponse>;
+    users: UsersClient;
+    wallets: WalletsClient;
+    transactions: TransactionsClient;
+    conversion: ConversionClient;
+    treasury: TreasuryClient;
+  }
+}

package/index.js

@@ -0,0 +1,292 @@
+/**
+ * Bitalcer Partner API — JavaScript SDK v1.0.0
+ *
+ * Cliente oficial para la Bitalcer Custody-as-a-Service Partner API.
+ * Firma HMAC-SHA256 automática. Sin dependencias externas.
+ *
+ * @example
+ *   const { Client } = require('@bitalcer/partner-api');
+ *   const bitalcer = new Client({ apiKey: 'bak_...', hmacSecret: '...' });
+ *   await bitalcer.ping();
+ *   const user = await bitalcer.users.create('cust-00001');
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Calcula la firma HMAC-SHA256 para un request.
+ * @param {string} secret - HMAC secret en hex
+ * @param {string} timestamp - Epoch en ms como string
+ * @param {string} body - Body crudo (string vacío para GET)
+ * @returns {string} Firma en hexadecimal
+ */
+function sign(secret, timestamp, body) {
+  return crypto
+    .createHmac('sha256', secret)
+    .update(timestamp + ':' + body)
+    .digest('hex');
+}
+
+/**
+ * Realiza un request firmado a la Partner API.
+ * @param {object} opts
+ * @param {string} opts.baseUrl
+ * @param {string} opts.apiKey
+ * @param {string} opts.hmacSecret
+ * @param {string} opts.method
+ * @param {string} opts.path
+ * @param {object} [opts.body]
+ * @returns {Promise<object>} Respuesta parseada como JSON
+ */
+async function request(opts) {
+  const { baseUrl, apiKey, hmacSecret, method, path, body } = opts;
+  const rawBody = body ? JSON.stringify(body) : '';
+  const timestamp = String(Date.now());
+  const signature = sign(hmacSecret, timestamp, rawBody);
+
+  const headers = {
+    'x-api-key': apiKey,
+    'x-timestamp': timestamp,
+    'x-signature': signature,
+  };
+  if (body) {
+    headers['Content-Type'] = 'application/json';
+  }
+
+  const url = baseUrl.replace(/\/+$/, '') + '/' + path.replace(/^\/+/, '');
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: rawBody || undefined,
+  });
+
+  const data = await res.json();
+
+  if (!res.ok) {
+    const err = new Error(data.error || data.message || `HTTP ${res.status}`);
+    err.status = res.status;
+    err.code = data.error;
+    err.body = data;
+    throw err;
+  }
+
+  return data;
+}
+
+// ── Client ────────────────────────────────────────────────────────────────
+
+class Client {
+  /**
+   * @param {object} config
+   * @param {string} config.apiKey - API key de sandbox o production
+   * @param {string} config.hmacSecret - HMAC secret correspondiente
+   * @param {string} [config.baseUrl='https://api.bitalcer.com']
+   */
+  constructor({ apiKey, hmacSecret, baseUrl = 'https://api.bitalcer.com' }) {
+    if (!apiKey || !hmacSecret) {
+      throw new Error('apiKey y hmacSecret son obligatorios.');
+    }
+    /** @private */ this._baseUrl = baseUrl;
+    /** @private */ this._apiKey = apiKey;
+    /** @private */ this._hmacSecret = hmacSecret;
+
+    this.users = new UsersClient(this);
+    this.wallets = new WalletsClient(this);
+    this.transactions = new TransactionsClient(this);
+    this.conversion = new ConversionClient(this);
+    this.treasury = new TreasuryClient(this);
+  }
+
+  /**
+   * Verifica conectividad y credenciales.
+   * @returns {Promise<{status: string, partner_id: number, environment: string}>}
+   */
+  async ping() {
+    return this._req('GET', '/partner/v1/ping');
+  }
+
+  /** @private */
+  _req(method, path, body) {
+    return request({
+      baseUrl: this._baseUrl,
+      apiKey: this._apiKey,
+      hmacSecret: this._hmacSecret,
+      method,
+      path,
+      body,
+    });
+  }
+}
+
+// ── Sub-clientes ──────────────────────────────────────────────────────────
+
+class UsersClient {
+  /** @private */ constructor(client) { this._c = client; }
+
+  /**
+   * Registra (u obtiene) un usuario del partner.
+   * Idempotente: si el external_user_id ya existe, devuelve el registro existente.
+   * @param {string} externalUserId - Identificador del usuario en tu sistema
+   * @returns {Promise<{id: number, partner_id: number, external_user_id: string, internal_user_id: number|null, status: string}>}
+   */
+  async create(externalUserId) {
+    return this._c._req('POST', '/partner/v1/users', { external_user_id: externalUserId });
+  }
+}
+
+class WalletsClient {
+  /** @private */ constructor(client) { this._c = client; }
+
+  /**
+   * Crea una wallet on-chain para un usuario.
+   * @param {string} externalUserId
+   * @param {'bsc'|'polygon'|'btc'} [chain='bsc']
+   * @returns {Promise<{external_user_id: string, address: string, chain: string}>}
+   */
+  async create(externalUserId, chain = 'bsc') {
+    return this._c._req('POST', '/partner/v1/wallets', { external_user_id: externalUserId, chain });
+  }
+
+  /**
+   * Consulta el saldo de un token en la wallet de un usuario.
+   * @param {string} externalUserId
+   * @param {{token?: string, chain?: string}} [opts]
+   * @returns {Promise<{external_user_id: string, token: string, chain: string, balance: string, address: string}>}
+   */
+  async getBalance(externalUserId, { token = 'USDT', chain = 'bsc' } = {}) {
+    const qs = `token=${token}&chain=${chain}`;
+    return this._c._req('GET', `/partner/v1/wallets/${externalUserId}/balance?${qs}`);
+  }
+
+  /**
+   * Obtiene la dirección de depósito. Si no existe wallet, la crea automáticamente.
+   * @param {string} externalUserId
+   * @param {{chain?: string}} [opts]
+   * @returns {Promise<{external_user_id: string, address: string, chain: string}>}
+   */
+  async getAddress(externalUserId, { chain = 'bsc' } = {}) {
+    return this._c._req('GET', `/partner/v1/wallets/${externalUserId}/address?chain=${chain}`);
+  }
+}
+
+class TransactionsClient {
+  /** @private */ constructor(client) { this._c = client; }
+
+  /**
+   * Retira fondos hacia una dirección externa. Descuenta del Partner Treasury.
+   * @param {object} params
+   * @param {string} params.externalUserId
+   * @param {string} params.toAddress - Dirección de destino
+   * @param {string} params.amount - Monto (ej. "100.00")
+   * @param {string} [params.token='USDT']
+   * @param {'bsc'|'polygon'} [params.chain='bsc']
+   * @returns {Promise<{withdraw_id: string, tx_hash: string, status: string}>}
+   */
+  async withdraw({ externalUserId, toAddress, amount, token = 'USDT', chain = 'bsc' }) {
+    return this._c._req('POST', '/partner/v1/transactions/withdraw', {
+      external_user_id: externalUserId,
+      to_address: toAddress,
+      amount,
+      token,
+      chain,
+    });
+  }
+
+  /**
+   * Transferencia interna instantánea entre dos usuarios del partner.
+   * @param {object} params
+   * @param {string} params.senderExternalUserId
+   * @param {string} params.receiverExternalUserId
+   * @param {string} params.amount
+   * @param {string} [params.token='USDT']
+   * @returns {Promise<{transfer_id: string, status: string}>}
+   */
+  async transfer({ senderExternalUserId, receiverExternalUserId, amount, token = 'USDT' }) {
+    return this._c._req('POST', '/partner/v1/transactions/transfer', {
+      sender_external_user_id: senderExternalUserId,
+      receiver_external_user_id: receiverExternalUserId,
+      amount,
+      token,
+    });
+  }
+}
+
+class ConversionClient {
+  /** @private */ constructor(client) { this._c = client; }
+
+  /**
+   * Paso 1/4: Cotiza conversión GTQ↔USDT sin crear orden.
+   * @param {object} params
+   * @param {string} params.externalUserId
+   * @param {'GTQ'|'USDT'} params.baseAsset
+   * @param {'GTQ'|'USDT'} params.quoteAsset
+   * @param {number} params.amount
+   * @returns {Promise<{pair: string, estimated_amount_out: number, price_applied: number}>}
+   */
+  async quote({ externalUserId, baseAsset, quoteAsset, amount }) {
+    const qs = `external_user_id=${externalUserId}&base_asset=${baseAsset}&quote_asset=${quoteAsset}&amount=${amount}`;
+    return this._c._req('GET', `/partner/v1/conversion/quote?${qs}`);
+  }
+
+  /**
+   * Paso 2/4: Crea una orden de conversión en estado quoted.
+   * @param {object} params
+   * @param {string} params.externalUserId
+   * @param {'GTQ'|'USDT'} params.baseAsset
+   * @param {'GTQ'|'USDT'} params.quoteAsset
+   * @param {number} params.requestedAmount
+   * @param {'buy'|'sell'} params.side
+   * @returns {Promise<{order_id: string, status: string, quote_expires_at: string}>}
+   */
+  async createOrder({ externalUserId, baseAsset, quoteAsset, requestedAmount, side }) {
+    return this._c._req('POST', '/partner/v1/conversion/orders', {
+      external_user_id: externalUserId,
+      base_asset: baseAsset,
+      quote_asset: quoteAsset,
+      requested_amount: requestedAmount,
+      side,
+    });
+  }
+
+  /**
+   * Paso 3/4: Ejecuta una orden de conversión.
+   * @param {string} externalUserId
+   * @param {string} orderId
+   * @returns {Promise<{order_id: string, status: string, executed_at: string}>}
+   */
+  async execute(externalUserId, orderId) {
+    return this._c._req('POST', '/partner/v1/conversion/execute', {
+      external_user_id: externalUserId,
+      order_id: orderId,
+    });
+  }
+
+  /**
+   * Paso 4/4: Consulta el estado de una orden.
+   * @param {string} externalUserId
+   * @param {string} orderId
+   * @returns {Promise<{order_id: string, status: string, executed_amount: number}>}
+   */
+  async getStatus(externalUserId, orderId) {
+    const qs = `external_user_id=${externalUserId}&order_id=${orderId}`;
+    return this._c._req('GET', `/partner/v1/conversion/status?${qs}`);
+  }
+}
+
+class TreasuryClient {
+  /** @private */ constructor(client) { this._c = client; }
+
+  /**
+   * Consulta el saldo del Partner Treasury (tu saldo prepagado en USD).
+   * @returns {Promise<{partner_id: number, available_balance_usd: number, reserved_balance_usd: number, tier: string}>}
+   */
+  async getBalance() {
+    return this._c._req('GET', '/partner/v1/treasury/balance');
+  }
+}
+
+module.exports = { Client };

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@bitalcer/partner-api",
+  "version": "1.0.0",
+  "description": "Bitalcer Custody-as-a-Service Partner API — SDK oficial para JavaScript/TypeScript. Firma HMAC-SHA256 automática, tipado completo.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "keywords": ["bitalcer", "crypto", "custody", "wallet", "api", "partner", "hmac", "usdt", "remesas"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bitalcer/partner-api-js"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}