spaps-types 1.5.0 → 1.5.1

package/src/index.ts

@@ -56,6 +56,26 @@ export interface UserWallet {
   updated_at: string;
 }
 
+export interface ApiDiagnostic {
+  code: string;
+  message: string;
+  status?: number | null;
+  details?: any;
+}
+
+export interface ApiRemediation {
+  kind: string;
+  label?: string | null;
+  method?: string | null;
+  path?: string | null;
+  cli?: string | null;
+  requires?: string[];
+  details?: any;
+  command_template?: string | null;
+  safe_to_execute?: boolean | null;
+  operator_gate_required?: boolean | null;
+}
+
 // API Response wrapper
 export interface ApiResponse<T = any> {
   success: boolean;
@@ -65,9 +85,14 @@ export interface ApiResponse<T = any> {
     message: string;
     details?: any;
   };
+  request_id?: string;
+  timestamp?: string;
+  diagnostics?: ApiDiagnostic[];
+  remediations?: ApiRemediation[];
   metadata?: {
     timestamp: string;
     request_id: string;
+    [key: string]: any;
   };
 }
 
@@ -640,11 +665,13 @@ export interface CryptoInvoiceResponse {
 export interface CryptoInvoiceStatusSnapshot {
   id: string;
   status: CryptoInvoiceStatus;
-  asset: CryptoAsset;
-  network: CryptoNetwork;
-  expires_at: string;
-  underpaid: boolean;
-  overpaid: boolean;
+  amount?: string;
+  asset?: CryptoAsset;
+  network?: CryptoNetwork;
+  expires_at?: string | null;
+  settled_at?: string | null;
+  underpaid?: boolean | string | null;
+  overpaid?: boolean | string | null;
 }
 
 export interface CryptoReconcileRequest {
@@ -652,6 +679,14 @@ export interface CryptoReconcileRequest {
   reconToken?: string;
 }
 
+export interface CryptoReconcileResult {
+  reconciled: boolean;
+  message?: string;
+  job_id?: string;
+  scheduled_at?: string;
+  cursor?: Record<string, any>;
+}
+
 export interface VerifyCryptoWebhookSignatureOptions {
   body: string | Uint8Array | Record<string, any>;
   signature: string | null | undefined;
@@ -896,6 +931,21 @@ export {
   type SecureMessageOutput
 } from './schemas/secureMessages';
 
+export {
+  SPAPS_WEBHOOK_EVENT_CATALOG,
+  SPAPS_WEBHOOK_EVENT_TYPES,
+  isSpapsWebhookEventType,
+  parseSpapsWebhookEnvelope,
+  spapsWebhookEnvelopeSchema,
+  verifyAndParseSpapsWebhook,
+  verifySpapsWebhookSignature,
+  type SpapsWebhookEnvelope,
+  type SpapsWebhookEventPayload,
+  type SpapsWebhookEventType,
+  type SpapsWebhookHmacSha256,
+  type VerifySpapsWebhookSignatureOptions,
+} from './webhook-events';
+
 // Re-export compatibility (helps with migration)
 export type JWTPayload = TokenPayload;
 export type DecodedToken = {

package/src/webhook-events.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod';
+
+import {
+  SPAPS_WEBHOOK_EVENT_CATALOG,
+  SPAPS_WEBHOOK_EVENT_TYPES,
+  type GeneratedSpapsWebhookEventType,
+} from './generated/webhookEventCatalog';
+
+declare const require: ((id: string) => unknown) | undefined;
+
+interface HmacLike {
+  update(data: string): HmacLike;
+  digest(encoding: 'hex'): string;
+}
+
+interface NodeCryptoLike {
+  createHmac?: (algorithm: 'sha256', key: string) => HmacLike;
+  timingSafeEqual?: (left: Uint8Array, right: Uint8Array) => boolean;
+}
+
+export { SPAPS_WEBHOOK_EVENT_CATALOG, SPAPS_WEBHOOK_EVENT_TYPES };
+
+export type SpapsWebhookEventType = GeneratedSpapsWebhookEventType;
+
+export type SpapsWebhookEventPayload<TEventType extends SpapsWebhookEventType = SpapsWebhookEventType> =
+  Record<string, unknown> & { readonly __eventType?: TEventType };
+
+export interface SpapsWebhookEnvelope<
+  TEventType extends SpapsWebhookEventType = SpapsWebhookEventType,
+  TData extends Record<string, unknown> = SpapsWebhookEventPayload<TEventType>
+> {
+  id: string;
+  type: TEventType;
+  schema_version: number;
+  application_id: string;
+  created_at: string;
+  data: TData;
+}
+
+export type SpapsWebhookHmacSha256 = (secret: string, payload: string) => string;
+
+export interface VerifySpapsWebhookSignatureOptions {
+  body: string | Uint8Array | object;
+  signature: string | null | undefined;
+  secret: string;
+  toleranceSeconds?: number;
+  nowSeconds?: number;
+  hmacSha256Hex?: SpapsWebhookHmacSha256;
+}
+
+const eventTypeSet = new Set<string>(SPAPS_WEBHOOK_EVENT_TYPES);
+
+export function isSpapsWebhookEventType(value: string): value is SpapsWebhookEventType {
+  return eventTypeSet.has(value);
+}
+
+export const spapsWebhookEnvelopeSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().refine(isSpapsWebhookEventType, {
+    message: 'unknown SPAPS webhook event type',
+  }),
+  schema_version: z.number().int().positive(),
+  application_id: z.string().min(1),
+  created_at: z.string().min(1),
+  data: z.record(z.string(), z.unknown()),
+});
+
+export function parseSpapsWebhookEnvelope(body: string | Uint8Array | object): SpapsWebhookEnvelope {
+  const parsed = typeof body === 'string' || body instanceof Uint8Array
+    ? JSON.parse(rawBodyToString(body))
+    : body;
+  return spapsWebhookEnvelopeSchema.parse(parsed) as SpapsWebhookEnvelope;
+}
+
+export function verifySpapsWebhookSignature(options: VerifySpapsWebhookSignatureOptions): boolean {
+  const {
+    body,
+    signature,
+    secret,
+    toleranceSeconds = 300,
+    nowSeconds,
+    hmacSha256Hex,
+  } = options;
+
+  if (!signature) {
+    throw new Error('Missing webhook signature');
+  }
+
+  const parts = parseSignatureHeader(signature);
+  const timestamp = parts.t;
+  const expected = parts.v1;
+  if (!timestamp || !expected) {
+    throw new Error('Invalid webhook signature format');
+  }
+
+  const rawBody = rawBodyToString(body);
+  const payload = `${timestamp}.${rawBody}`;
+  const computed = (hmacSha256Hex ?? defaultHmacSha256Hex)(secret, payload);
+
+  if (!timingSafeHexEqual(expected, computed)) {
+    throw new Error('Invalid webhook signature');
+  }
+
+  const timestampSeconds = Number(timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    throw new Error('Invalid webhook signature timestamp');
+  }
+  if (toleranceSeconds > 0) {
+    const currentSeconds = nowSeconds ?? Date.now() / 1000;
+    if (Math.abs(currentSeconds - timestampSeconds) > toleranceSeconds) {
+      throw new Error('Webhook signature timestamp outside tolerance window');
+    }
+  }
+
+  return true;
+}
+
+export function verifyAndParseSpapsWebhook(options: VerifySpapsWebhookSignatureOptions): SpapsWebhookEnvelope {
+  verifySpapsWebhookSignature(options);
+  return parseSpapsWebhookEnvelope(options.body);
+}
+
+function parseSignatureHeader(signature: string): Record<string, string> {
+  return signature.split(',').reduce<Record<string, string>>((accumulator, part) => {
+    const [key, value] = part.split('=');
+    if (key && value) {
+      accumulator[key.trim()] = value.trim();
+    }
+    return accumulator;
+  }, {});
+}
+
+function rawBodyToString(body: string | Uint8Array | object): string {
+  if (typeof body === 'string') {
+    return body;
+  }
+  if (body instanceof Uint8Array) {
+    return utf8BytesToString(body);
+  }
+  return JSON.stringify(body ?? {});
+}
+
+function utf8BytesToString(bytes: Uint8Array): string {
+  let encoded = '';
+  for (const byte of bytes) {
+    encoded += `%${byte.toString(16).padStart(2, '0')}`;
+  }
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    throw new Error('Webhook body bytes must be valid UTF-8');
+  }
+}
+
+function defaultHmacSha256Hex(secret: string, payload: string): string {
+  const cryptoModule = loadNodeCrypto();
+  if (!cryptoModule?.createHmac) {
+    throw new Error('No HMAC-SHA256 provider available; pass hmacSha256Hex');
+  }
+  const hmac = cryptoModule.createHmac('sha256', secret);
+  hmac.update(payload);
+  return hmac.digest('hex');
+}
+
+function loadNodeCrypto(): NodeCryptoLike | undefined {
+  if (typeof require !== 'function') {
+    return undefined;
+  }
+  try {
+    return require('crypto') as NodeCryptoLike;
+  } catch {
+    return undefined;
+  }
+}
+
+function timingSafeHexEqual(expectedHex: string, computedHex: string): boolean {
+  const expected = hexToBytes(expectedHex);
+  const computed = hexToBytes(computedHex);
+  if (expected.length !== computed.length) {
+    return false;
+  }
+  const cryptoModule = loadNodeCrypto();
+  if (cryptoModule?.timingSafeEqual) {
+    return cryptoModule.timingSafeEqual(expected, computed);
+  }
+  let diff = 0;
+  for (let index = 0; index < expected.length; index += 1) {
+    diff |= expected[index] ^ computed[index];
+  }
+  return diff === 0;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(hex)) {
+    throw new Error('Invalid webhook signature digest');
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < hex.length; index += 2) {
+    bytes[index / 2] = Number.parseInt(hex.slice(index, index + 2), 16);
+  }
+  return bytes;
+}