@makegov/tango-node 0.1.4

package/.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.eslintrc.cjs

@@ -0,0 +1,20 @@
+/* eslint-env node */
+module.exports = {
+  root: true,
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    ecmaVersion: "latest",
+    sourceType: "module",
+  },
+  env: {
+    node: true,
+    es2022: true,
+  },
+  plugins: ["@typescript-eslint"],
+  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  ignorePatterns: ["dist/", "node_modules/"],
+  rules: {
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+  },
+};

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "printWidth": 150,
+  "tabWidth": 2,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "semi": true,
+  "arrowParens": "always"
+}

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `@makegov/tango-node` will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2025-11-21
+
+- Initial Node.js port of the Tango Python SDK.
+- Basic project scaffolding for client, models, and shapes.
+- ESM + TypeScript build configuration.
+
+## [0.1.4] - 2025-11-21
+
+- Added tests and cleaned up formatting and structure of SDK.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MakeGov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,331 @@
+# Tango Node SDK
+
+A modern Node.js SDK for the [Tango API](https://tango.makegov.com), featuring dynamic response shaping, strong TypeScript types, and full coverage of the core Tango endpoints.
+
+> This is the Node/TypeScript port of the official Tango Python SDK.
+
+## Features
+
+- **Dynamic Response Shaping** – Ask Tango for exactly the fields you want using a simple shape syntax.
+- **Type-Safe by Design** – Shape strings are validated against Tango schemas and mapped to generated TypeScript types.
+- **Comprehensive API Coverage** – Agencies, business types, entities, contracts, forecasts, opportunities, notices, and grants.
+- **Flexible Data Access** – Plain JavaScript objects backed by runtime validation and parsing, materialized via the dynamic model pipeline.
+- **Modern Node** – Built for Node 18+ with native `fetch` and ESM-first design.
+- **Tested Against the Real API** – Integration tests (mirroring the Python SDK) keep behavior aligned.
+
+## Installation
+
+**Requirements:** Node 18 or higher.
+
+```bash
+npm install @makegov/tango-node
+# or
+yarn add @makegov/tango-node
+# or
+pnpm add @makegov/tango-node
+```
+
+## Quick Start
+
+### Initialize the client
+
+```ts
+import { TangoClient } from "@makegov/tango-node";
+
+const client = new TangoClient({
+  apiKey: process.env.TANGO_API_KEY,
+  // baseUrl: "https://tango.makegov.com", // default
+});
+```
+
+### List agencies
+
+```ts
+const agencies = await client.listAgencies();
+
+for (const agency of agencies.results) {
+  console.log(agency.code, agency.name);
+}
+```
+
+### Get a specific agency
+
+```ts
+const treasury = await client.getAgency("2000"); // Treasury
+console.log(treasury.name, treasury.department?.name);
+```
+
+### Search contracts with a minimal shape
+
+```ts
+import { TangoClient, ShapeConfig } from "@makegov/tango-node";
+
+const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
+
+const contracts = await client.listContracts({
+  shape: ShapeConfig.CONTRACTS_MINIMAL,
+  keyword: "cloud services",
+  awarding_agency: "4700",
+  fiscal_year: 2024,
+  limit: 10,
+});
+
+// Each contract is shaped according to CONTRACTS_MINIMAL
+for (const c of contracts.results) {
+  console.log(c.piid, c.award_date, c.recipient.display_name);
+}
+```
+
+### Get a fully-shaped entity
+
+```ts
+import { TangoClient, ShapeConfig } from "@makegov/tango-node";
+
+const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
+
+const entity = await client.getEntity("ABC123DEF456", {
+  shape: ShapeConfig.ENTITIES_COMPREHENSIVE,
+});
+
+console.log(entity.uei, entity.legal_business_name, entity.primary_naics);
+```
+
+## Authentication
+
+The Node SDK uses the same model as the Python one: you can either pass the API key directly or read it from `TANGO_API_KEY`.
+
+### With API key
+
+```ts
+import { TangoClient } from "@makegov/tango-node";
+
+const client = new TangoClient({
+  apiKey: "your-api-key-here",
+});
+```
+
+### From environment variable (`TANGO_API_KEY`)
+
+```ts
+import { TangoClient } from "@makegov/tango-node";
+
+const client = new TangoClient();
+// If apiKey is omitted, the client will look for process.env.TANGO_API_KEY
+```
+
+## Core Concepts
+
+### Dynamic Response Shaping
+
+Response shaping is the core feature of Tango. Instead of always receiving huge objects with every field, you describe the fields you want with a compact shape string:
+
+```ts
+const contracts = await client.listContracts({
+  shape: "key,piid,award_date,recipient(display_name),total_contract_value",
+  keyword: "software",
+  limit: 5,
+});
+```
+
+**Shapes:**
+
+- Reduce payload size (often massively).
+- Keep responses focused on what your app actually uses.
+- Drive type safety – the SDK maps the shape to a TypeScript type.
+
+**The Node SDK includes:**
+
+- A **shape parser** that validates shape strings.
+- A **schema registry** that knows what fields exist on each resource.
+- A **type generator** and **model factory** that convert raw API JSON into strongly-typed objects.
+
+### Flat vs nested responses
+
+By default, nested fields are returned as nested objects:
+
+```ts
+// shape:
+"key,piid,recipient(display_name,uei)";
+
+//
+contract.recipient.display_name;
+contract.recipient.uei;
+```
+
+You can request a "flat" representation that uses dotted keys and then unflattens into nested objects on the client:
+
+```ts
+const contracts = await client.listContracts({
+  shape: ShapeConfig.CONTRACTS_MINIMAL,
+  flat: true,
+});
+```
+
+The Node SDK mirrors the Python client's behavior for `shape`, `flat`, and `flat_lists`.
+
+## API Methods
+
+The Node client mirrors the Python SDK's high-level API:
+
+- `listAgencies(options)`
+- `getAgency(code)`
+- `listBusinessTypes(options)`
+- `listContracts(options)`
+- `listEntities(options)`
+- `getEntity(ueiOrCage, options)`
+- `listForecasts(options)`
+- `listOpportunities(options)`
+- `listNotices(options)`
+- `listGrants(options)`
+
+All list methods return a paginated response:
+
+```ts
+interface PaginatedResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  pageMetadata: Record<string, unknown> | null;
+  results: T[];
+}
+```
+
+## Error Handling
+
+Errors are surfaced as typed exceptions, aligned with the Python SDK:
+
+- `TangoAPIError` – Base error for unexpected issues.
+- `TangoAuthError` – Authentication problems (e.g., invalid API key, 401).
+- `TangoNotFoundError` – Resource not found (404).
+- `TangoValidationError` – Invalid request parameters (400).
+- `TangoRateLimitError` – Rate limit exceeded (429).
+
+Shape-related errors:
+
+- `ShapeError`
+- `ShapeValidationError`
+- `ShapeParseError`
+- `TypeGenerationError`
+- `ModelInstantiationError`
+
+Use them in your code:
+
+```ts
+import { TangoClient, TangoAPIError, TangoValidationError } from "@makegov/tango-node";
+
+try {
+  const resp = await client.listContracts({ keyword: "cloud", limit: 5 });
+} catch (err) {
+  if (err instanceof TangoValidationError) {
+    console.error("Bad request:", err.message);
+  } else if (err instanceof TangoAPIError) {
+    console.error("Tango API error:", err.message);
+  } else {
+    console.error("Unexpected error:", err);
+  }
+}
+```
+
+## Project Structure
+
+```text
+tango-node/
+├── src/                         # Source TypeScript
+│   ├── client.ts                # TangoClient implementation
+│   ├── config.ts                # Default base URL + shape presets
+│   ├── errors.ts                # Error classes (API, auth, validation, etc.)
+│   ├── index.ts                 # Public API exports
+│   ├── types.ts                 # Shared types (options, PaginatedResponse)
+│   ├── models/                  # Lightweight model interfaces (Contract, Entity, etc.)
+│   ├── shapes/                  # Shape system (parser, generator, factory)
+│   │   ├── explicitSchemas.ts   # Predefined schemas for resources
+│   │   ├── factory.ts           # Instantiate typed models from data
+│   │   ├── generator.ts         # Type generation from shape specs
+│   │   ├── index.ts             # Shapes exports
+│   │   ├── parser.ts            # Shape string parser
+│   │   ├── schema.ts            # Schema registry + validation
+│   │   ├── schemaTypes.ts       # Schema data structures
+│   │   └── types.ts             # Shape spec types
+│   └── utils/                   # Helpers
+│       ├── dates.ts             # Date/time parsing utilities
+│       ├── http.ts              # HTTP client wrapper
+│       ├── number.ts            # Numeric parsing/formatting
+│       └── unflatten.ts         # Unflatten dotted-key responses
+├── docs/                        # Documentation
+│   ├── API_REFERENCE.md
+│   ├── DYNAMIC_MODELS.md
+│   └── SHAPED.md
+├── tests/                       # Test suite (Vitest)
+│   └── unit/
+│       ├── client.test.ts
+│       ├── errors.test.ts
+│       ├── shapes.factory.test.ts
+│       ├── shapes.generator.test.ts
+│       ├── shapes.parser.test.ts
+│       ├── shapes.schema.test.ts
+│       ├── utils.dates.test.ts
+│       ├── utils.http.test.ts
+│       ├── utils.number.test.ts
+│       └── utils.unflatten.test.ts
+├── dist/                        # Build output (compiled JS + d.ts) from `npm run build`
+├── eslint.config.js             # ESLint flat config
+├── .prettierrc                  # Prettier config
+├── package.json                 # Package metadata/scripts
+├── tsconfig.json                # TypeScript config
+├── README.md                    # Usage docs
+├── CHANGELOG.md                 # Version history
+└── LICENSE                      # MIT license
+```
+
+## Development
+
+After cloning the repo:
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Useful scripts:
+
+- `npm run build` – Compile TypeScript to `dist/`.
+- `npm test` – Run unit and integration tests.
+- `npm run coverage` – Get test coverage report.
+- `npm run lint` – Run ESLint.
+- `npm run format` – Run Prettier.
+- `npm run typecheck` – TS type checking without emit.
+
+## Requirements
+
+- Node 18 or higher.
+- A valid [Tango API key](https://tango.makegov.com/).
+
+## Documentation
+
+- [API Reference](docs/API_REFERENCE.md) - Detailed API documentation
+- [Shape System Guide](docs/SHAPES.md) - Comprehensive guide to response shaping
+- [Dynamic Models Guide](docs/DYNAMIC_MODELS.md) - ynamic shaping system\*\* works.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+For questions, issues, or feature requests:
+
+- **Email**: [tango@makegov.com](mailto:tango@makegov.com)
+- **Issues**: [GitHub Issues](https://github.com/makegov/tango-node/issues)
+- **Documentation**: [https://tango.makegov.com/docs/tango-node](https://tango.makegov.com/docs/tango-node) _(Coming Soon!)_
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`npm run test`)
+4. Commit your changes (`git commit -m 'Add amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import { PaginatedResponse, TangoClientOptions } from "./types.js";
+type AnyRecord = Record<string, unknown>;
+export interface ListOptionsBase {
+    page?: number;
+    limit?: number;
+    shape?: string | null;
+    flat?: boolean;
+    flatLists?: boolean;
+}
+export interface ListContractsOptions extends ListOptionsBase {
+    filters?: AnyRecord;
+    [key: string]: unknown;
+}
+export interface ListEntitiesOptions extends ListOptionsBase {
+    search?: string;
+    [key: string]: unknown;
+}
+export declare class TangoClient {
+    private readonly http;
+    private readonly shapeParser;
+    private readonly modelFactory;
+    constructor(options?: TangoClientOptions);
+    listAgencies(options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<AnyRecord>>;
+    getAgency(code: string): Promise<AnyRecord>;
+    listBusinessTypes(options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<AnyRecord>>;
+    listContracts(options?: ListContractsOptions): Promise<PaginatedResponse<Record<string, unknown>>>;
+    listEntities(options?: ListEntitiesOptions): Promise<PaginatedResponse<Record<string, unknown>>>;
+    getEntity(key: string, options?: {
+        shape?: string | null;
+        flat?: boolean;
+        flatLists?: boolean;
+    }): Promise<Record<string, unknown>>;
+    listForecasts(options?: ListOptionsBase & Record<string, unknown>): Promise<PaginatedResponse<Record<string, unknown>>>;
+    listOpportunities(options?: ListOptionsBase & Record<string, unknown>): Promise<PaginatedResponse<Record<string, unknown>>>;
+    listNotices(options?: ListOptionsBase & Record<string, unknown>): Promise<PaginatedResponse<Record<string, unknown>>>;
+    listGrants(options?: ListOptionsBase & Record<string, unknown>): Promise<PaginatedResponse<Record<string, unknown>>>;
+    private parseShape;
+    private materializeList;
+    private materializeOne;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}