yahoo-finance2 AGENTS.md

Agent Notes

This file applies to the whole repository. For fuller contributor guidance, read CONTRIBUTING.md; this file repeats the essentials agents are most likely to need during edits.

Project Context

• This is a Deno-first TypeScript library that is published to npm via generated output.
• Source code lives under src/. Tests usually sit beside the module they cover and use fixtures from tests/fixtures/http.
• The npm/ directory is generated package output. Prefer editing source files under src/ and regenerate npm output only when the task explicitly calls for it.
• The default development branch is dev.

Commands

• Run the full test suite with deno task test.
• Run a targeted test with deno task test path/to/file.test.ts.
• Run serial tests with deno task test:serial path/to/file.test.ts when debugging or limiting live Yahoo request concurrency.
• Run schema generation with deno task schema after changing exported interfaces marked with @yf-schema.
• Use deno fmt and deno lint for formatting and linting.
• Build npm output with deno task build:npm when generated npm artifacts are required.

Testing And Fixtures

• Tests use fetch-mock-cache and cached HTTP fixtures for repeatability.
• New module tests should call setupCache() from tests/common.ts when they touch Yahoo HTTP responses.
• FETCH_DEVEL=nocache forces live network tests without cache.
• FETCH_DEVEL=recache updates cache for failing tests. Be careful with fixture churn, and do not recache files ending in .static.json or .fake.json.
• Before committing recached fixtures, inspect their HTTP status and payload. Do not commit transient failures such as rate limits, consent interstitials, timeouts, or upstream 5xx responses as replacements for successful fixtures.

Schema And Validation

• TypeScript interfaces in module files are the source of truth for runtime validation schemas.
• If a module file has @yf-schema, keep the generated .schema.json file in sync with deno task schema.
• Prefer updating typed interfaces and validation schemas together with focused tests that cover the Yahoo response shape involved.
• When Yahoo adds a response field, model it as required first. Make it optional only when other cached valid responses demonstrate that the field is absent, and add descriptive JSDoc for newly exposed fields.