TypeScript

npm install @hometown-workforce/estimator

Requiere Node.js 20.19 o más reciente. Úsalo en tu servidor: la llave que recibe es secreta.

Haz una estimación

import { Hometown } from '@hometown-workforce/estimator';

const hometown = new Hometown({ apiKey: process.env.HOMETOWN_API_KEY! });

const estimate = await hometown.estimates.create({ input: { text: 'sandbox:priced' } });
console.log(estimate.status, estimate.price);

Cada llamada que lleva tu llave es un método de un recurso: hometown.estimates.retrieve(id), hometown.customers.list({ limit: 20 }), hometown.webhookEndpoints.create({ ... }). El último argumento de cada uno acepta un AbortSignal y un timeout por intento. En estimates.create, estimates.followUp y customers.create acepta además tu propio idempotencyKey.

Atrapa errores

import { HometownError, InsufficientCreditsError } from '@hometown-workforce/estimator';

try {
  await hometown.estimates.create({ input: { text: 'Paint a 12 by 14 ft bedroom' } });
} catch (error) {
  if (error instanceof InsufficientCreditsError) {
    // compra créditos en el panel
  } else if (error instanceof HometownError) {
    console.error(error.code, error.requestId);
  } else {
    throw error;
  }
}

Los nombres de las clases siguen a los códigos: rate_limited es RateLimitedError y validation_failed es ValidationFailedError. Una petición que nunca recibe respuesta lanza ConnectionError.

Revisa un webhook

Pasa el cuerpo tal como llegó, antes de leerlo como JSON. Con Express, léelo con express.raw():

import { verifyWebhook } from '@hometown-workforce/estimator';

const event = await verifyWebhook(req.body, req.get('Hometown-Signature'), process.env.HOMETOWN_WEBHOOK_SECRET!);

Lanza WebhookSignatureError cuando ninguna firma coincide o la hora de la entrega se aleja más de cinco minutos.