cargo-core-api-sdk (TypeScript)

SDK oficial de TypeScript para la API pública de Rappi Cargo (cargo-core-api): Order V3, Picking Point, User, RT y Authorization.

Este paquete vive dentro del monorepo multi-lenguaje — ver el README raíz para la estructura general y el ROADMAP para la visión de otros lenguajes.

Estado: en construcción. Ver el plan completo en .claude/plans de cargo-core-api (o pedir el plan quirky-roaming-biscuit.md). No publicado todavía a ningún registry.

Quickstart

import { CargoClient } from "@rappi_cargo/cargo-core-api-sdk";

const client = new CargoClient({
  apiKey: process.env.CARGO_API_KEY!, // header user-token, provisto por tu KAM de Rappi Cargo
  environment: "dev", // "dev" | "co" | "mx" | "ar" | "uy" | "br" | "cl" | "cr" | "ec" | "pe"
});

const order = await client.orderV3.createOrder({
  order_id: "my-unique-id",
  total_value: 40000,
  payment_method: "ONLINE",
  vehicle_type: "BIKE",
  action_points: [
    /* ... */
  ],
  client_info: {
    /* ... */
  },
});

Todos los métodos devuelven una Promise que resuelve con el body tipado de la respuesta 2xx, o rechaza con:

• CargoApiError — cualquier respuesta no-2xx, con .status, .code, .type, .message (mapea ApiErrorDto).
• CargoNetworkError — timeout o fallo de red antes de recibir respuesta.

Examples

Ver examples/ — scripts completos y corribles por flujo real (crear/cancelar una orden, registrar un picking point, crear un usuario, devolución de efectivo, manejo de errores). Se chequean con typecheck junto con src/ y test/, así que no pueden desactualizarse en silencio.

Módulos

| Cliente | Métodos | |---|---| | client.orderV3 | createOrder, validateOrder, cancelOrder, getOrderStatus, listOrders, markOrderReady | | client.pickingPoints | createPickingPoint, updatePickingPoint, deletePickingPoint, listPickingPoints, findNearbyPickingPoints, getPickingPoint, getCheckinCode, getAllCheckinCodes, refreshCheckinCode | | client.users | createUser, updateUser, deleteUser, listUsers, getUser | | client.rt | confirmOrderReturn | | client.authorization | listPermissionGroups |

Desarrollo

Monorepo con npm workspaces — instalar siempre desde la raíz del repo, no acá:

npm install                              # desde la raíz del repo
npm run sync-and-generate -w packages/typescript   # sincroniza spec/openapi.yaml (raíz) y regenera src/generated/types.ts
npm run lint -w packages/typescript
npm test -w packages/typescript
npm run build -w packages/typescript

O, parado dentro de packages/typescript, usar los mismos scripts sin -w (siguen resolviendo contra el node_modules hoisted en la raíz).

Si tu cambio va a entrar en un release, corré npx changeset desde la raíz antes de commitear — ver la sección Versionado del README raíz.

Fuente del spec

Los tipos se generan desde ../../spec/openapi.yaml — el contrato OpenAPI compartido por todos los paquetes del monorepo (no solo este), sincronizado desde el portal público https://cargo-docs.dev.rappi.com/docs.yaml vía npm run sync-spec (que llama a ../../scripts/sync-openapi.sh). Si el portal no está disponible, corre npm run export:openapi en un checkout de cargo-core-api sobre master y copia el openapi.yaml resultante a spec/openapi.yaml en la raíz de este repo.

Gaps conocidos del spec (heredados, no del SDK)

• Dos endpoints de pickingPoints no declaran sus parámetros en el spec público (@ApiParam/@ApiQuery faltantes en cargo-core-api), tipados a mano directamente contra el código fuente: getPickingPoint(id) (GET /picking-point/view/:id) y getCheckinCode(pickingPointId) (GET /picking-point/checkin?p=...). Ver comentarios en src/modules/picking-point/client.ts.
• ~20 campos más (Order V3 y PickingPoint) resuelven a un tipo Record<string, never> inutilizable en el spec generado (@ApiProperty con type inválido, o sin type por un gap de reflection en el alias Optional<T>). Corregidos en src/core/spec-patches.ts, con cada campo documentado contra el código fuente real de cargo-core-api.

Ninguno de los dos requiere acción tuya como consumidor — ya están parcheados. Quedan documentados acá por si en algún momento se corrigen upstream (entonces el parche correspondiente en spec-patches.ts se vuelve innecesario y se puede borrar).

Licencia

MIT