@makegov/tango-node 0.1.4

package/docs/API_REFERENCE.md

@@ -0,0 +1,201 @@
+# Tango Node SDK – API Reference
+
+This document provides the full API reference for the **Node.js / TypeScript**
+version of the Tango SDK. It is a translation of the Python SDK documentation,
+rewritten for JavaScript runtime semantics, async/await, and the TypeScript
+type system.
+
+## Importing
+
+```ts
+import { TangoClient, ShapeConfig } from "@makegov/tango-node";
+// Models (optional)
+import type { Contract } from "@makegov/tango-node/models";
+```
+
+All methods are async and return Promises.
+
+---
+
+## Agencies
+
+### `listAgencies(options?)`
+
+List federal departments and subagencies.
+
+```ts
+const resp = await client.listAgencies({ page: 1, limit: 25 });
+```
+
+#### Parameters
+
+| Name    | Type     | Description                                 |
+| ------- | -------- | ------------------------------------------- |
+| `page`  | `number` | Page number (default 1).                    |
+| `limit` | `number` | Max results per page (default 25, max 100). |
+
+#### Returns
+
+`PaginatedResponse<AgencyLike>`
+
+---
+
+### `getAgency(code)`
+
+Fetch a single agency by its code.
+
+```ts
+const agency = await client.getAgency("2000");
+```
+
+Returns a shaped Agency object. Responses are materialized via the dynamic model pipeline (dates parsed, nested objects built).
+
+---
+
+## Business Types
+
+### `listBusinessTypes(options?)`
+
+Lists SBA/USASpending business type entries.
+
+```ts
+const types = await client.listBusinessTypes();
+```
+
+---
+
+## Contracts
+
+### `listContracts(options)`
+
+Search and list contract records.
+
+```ts
+const resp = await client.listContracts({
+  keyword: "cloud",
+  naics_code: "541511",
+  shape: ShapeConfig.CONTRACTS_MINIMAL,
+  flat: true,
+});
+```
+
+#### Search / Filter Parameters
+
+These mirror the Python SDK:
+
+| Filter           | Maps to API param |
+| ---------------- | ----------------- |
+| `keyword`        | `search`          |
+| `naics_code`     | `naics`           |
+| `psc_code`       | `psc`             |
+| `recipient_name` | `recipient`       |
+| `recipient_uei`  | `uei`             |
+| `set_aside_type` | `set_aside`       |
+
+Sorting:
+
+```ts
+sort: "award_date",
+order: "desc"   // -> ordering="-award_date"
+```
+
+Pagination + shaping options:
+
+```ts
+shape: string,
+flat: boolean,
+flatLists: boolean,
+page: number,
+limit: number
+```
+
+#### Returns
+
+`PaginatedResponse<Contract>` materialized according to the requested shape. Date/datetime fields are parsed, decimals normalized to strings, nested recipients, agencies, and locations are objects.
+
+---
+
+## Entities
+
+### `listEntities(options)`
+
+```ts
+const resp = await client.listEntities({
+  search: "Acme",
+  shape: ShapeConfig.ENTITIES_MINIMAL,
+});
+```
+
+Filters:
+
+- `search`
+- any field names supported by the API
+
+### `getEntity(uei, options?)`
+
+Fetch a single entity by UEI or CAGE.
+
+Returns a shaped entity object with nested addresses/fields based on the shape.
+
+---
+
+## Forecasts
+
+### `listForecasts(options)`
+
+Forecast search, with optional shaping.
+
+---
+
+## Opportunities
+
+### `listOpportunities(options)`
+
+Search SAM.gov opportunities with shaping.
+
+---
+
+## Notices
+
+### `listNotices(options)`
+
+---
+
+## Grants
+
+### `listGrants(options)`
+
+---
+
+## Error Types
+
+All thrown by async methods:
+
+- `TangoAPIError`
+- `TangoAuthError`
+- `TangoNotFoundError`
+- `TangoRateLimitError`
+- `TangoValidationError`
+- `ShapeError`
+- `ShapeParseError`
+- `ShapeValidationError`
+- `TypeGenerationError`
+- `ModelInstantiationError`
+
+---
+
+## Pagination
+
+All list endpoints return:
+
+```ts
+interface PaginatedResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  pageMetadata: Record<string, unknown> | null;
+  results: T[];
+}
+```
+
+You can follow `next` / `previous` manually or use your own wrapper.

package/docs/DYNAMIC_MODELS.md

@@ -0,0 +1,127 @@
+# Tango Node SDK – Dynamic Models Guide
+
+This document explains how the **Node.js dynamic shaping system** works.
+It is a full translation of the Python `DEVELOPERS.md` shaping guide.
+
+---
+
+## Overview
+
+Tango’s dynamic modeling allows you to:
+
+- Request _exactly the fields you want_
+- Validate the shape string against Tango’s schemas
+- Generate a typed model descriptor at runtime
+- Materialize shaped objects using correct:
+  - date parsing
+  - datetime parsing
+  - decimal handling
+  - list vs scalar logic
+  - nested structure
+
+---
+
+## Components
+
+### ShapeParser
+
+Parses shape strings into a `ShapeSpec`.
+
+```ts
+import { ShapeParser } from "@makegov/tango-node/shapes";
+
+const parser = new ShapeParser();
+const spec = parser.parse("key,piid,recipient(display_name)");
+```
+
+### SchemaRegistry
+
+Holds the field schemas for all models.
+
+```ts
+import { SchemaRegistry } from "@makegov/tango-node/shapes";
+
+const registry = new SchemaRegistry();
+registry.getField("Contract", "award_date");
+```
+
+### TypeGenerator
+
+Builds a `GeneratedModel` descriptor from `(baseModel, shapeSpec)`.
+
+```ts
+import { TypeGenerator } from "@makegov/tango-node/shapes";
+
+const gen = new TypeGenerator();
+const model = gen.generateModelDescriptor("Contract", spec);
+```
+
+### ModelFactory
+
+Takes a descriptor + raw API JSON and produces typed shaped objects. The TangoClient now uses this pipeline automatically after fetching data.
+
+```ts
+import { TangoClient } from "@makegov/tango-node";
+
+const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
+const contracts = await client.listContracts({
+  shape: "key,award_date,recipient(display_name)",
+});
+
+// contracts.results are materialized via ModelFactory:
+// - date/datetime parsed to Date
+// - decimals normalized to string
+// - nested structures enforced
+```
+
+---
+
+## Example: Full Shaping Pipeline (manual)
+
+```ts
+const parser = new ShapeParser();
+const spec = parser.parse("key,award_date,recipient(display_name)");
+
+const gen = new TypeGenerator();
+const descriptor = gen.generateModelDescriptor("Contract", spec);
+
+const factory = new ModelFactory();
+const shaped = factory.createOne("Contract", spec, {
+  key: "C-1",
+  award_date: "2024-01-15",
+  recipient: { display_name: "Acme" },
+});
+```
+
+`shaped` becomes:
+
+```ts
+{
+  key: "C-1",
+  award_date: Date("2024-01-15"),
+  recipient: { display_name: "Acme" }
+}
+```
+
+---
+
+## Type Safety
+
+Node SDK enforces shape correctness at runtime and guarantees nested structures. The client materializes responses through ModelFactory, so the shape schema is applied automatically. TypeScript interfaces are not codegenerated per shape at build time; the SDK exports lightweight model interfaces in `@makegov/tango-node/models` for convenience.
+
+---
+
+## Caching
+
+TypeGenerator caches descriptors with FIFO eviction.
+
+ShapeParser also caches parse results.
+
+---
+
+## Nested Models
+
+If a field is nested in the schema (e.g. `"recipient"` → `RecipientProfile`),
+the generator recursively builds the nested descriptor.
+
+---

package/docs/SHAPES.md

@@ -0,0 +1,94 @@
+# Tango Node SDK – Shaping Guide
+
+A complete translation of the Python SHAPES.md document for Node.
+
+---
+
+## Why Shapes?
+
+Tango resources can have hundreds of fields. Shapes let you request:
+
+- Only what you need
+- In nested form
+- With aliases
+- With wildcards
+- With flattening options
+
+---
+
+## Shape Grammar
+
+```
+shape       := field_list
+field_list  := field ("," field)*
+field       := field_name [alias] [nested]
+field_name  := identifier | "*"
+alias       := "::" identifier
+nested      := "(" field_list ")"
+identifier  := [a-zA-Z_][a-zA-Z0-9_]*
+```
+
+---
+
+## Examples
+
+### Simple
+
+```ts
+shape: "key,piid,award_date";
+```
+
+### Nested
+
+```ts
+shape: "recipient(display_name,uei)";
+```
+
+### Aliases
+
+```ts
+shape: "recipient::vendor(display_name)";
+```
+
+### Wildcard
+
+```ts
+shape: "*";
+```
+
+### Wildcard nested
+
+```ts
+shape: "recipient(*)";
+```
+
+---
+
+## Flat Responses
+
+```ts
+shape: ShapeConfig.CONTRACTS_MINIMAL,
+flat: true
+```
+
+The Tango API returns dotted keys; the SDK unflattens them:
+
+```ts
+recipient.display_name → recipient.display_name
+```
+
+---
+
+## Validation
+
+ShapeParser enforces syntax.
+
+TypeGenerator enforces semantic model rules (existence of fields, nested models).
+
+---
+
+## Performance Tips
+
+- Use minimal shapes in production.
+- Avoid full-wildcard unless you need all fields.
+- Prefer shallow nested shapes for large nested structures.

package/eslint.config.js

@@ -0,0 +1,37 @@
+import js from "@eslint/js";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import globals from "globals";
+
+export default [
+  {
+    ignores: ["dist/**", "node_modules/**"],
+  },
+  {
+    files: ["**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: import.meta.dirname,
+        sourceType: "module",
+      },
+      globals: {
+        ...globals.node,
+        ...globals.browser,
+        fetch: "readonly",
+        Request: "readonly",
+        Response: "readonly",
+        Headers: "readonly",
+        AbortController: "readonly",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs["recommended-type-checked"].rules,
+    },
+  },
+];

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@makegov/tango-node",
+  "version": "0.1.4",
+  "description": "Official Node.js SDK for the Tango API – dynamic response shaping, typed models, and full endpoint coverage.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./models": {
+      "import": "./dist/models/index.js",
+      "types": "./dist/models/index.d.ts",
+      "default": "./dist/models/index.js"
+    },
+    "./shapes": {
+      "import": "./dist/shapes/index.js",
+      "types": "./dist/shapes/index.d.ts",
+      "default": "./dist/shapes/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "keywords": [
+    "tango",
+    "makegov",
+    "federal-contracts",
+    "procurement",
+    "grants",
+    "sdk",
+    "api-client",
+    "govtech"
+  ],
+  "author": "MakeGov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makegov/tango-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/makegov/tango-node/issues"
+  },
+  "homepage": "https://github.com/makegov/tango-node#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.12.0",
+    "prettier": "^3.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "dependencies": {}
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "types": ["node", "vitest"]
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: true,
+    include: ["tests/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html"],
+      exclude: [".*", "*.config.*s", "dist/**/**", "src/index.ts", "src/shapes/index.ts", "tests/**/**"],
+    },
+  },
+  esbuild: {
+    loader: "ts",
+    target: "es2020",
+  },
+});