Add TypeScript declarations for the existing public surface

[mapitman]

Closes #56.

Adds hand-written type declarations for the SDK as it exists today. Scope is deliberately narrow: only the things the SDK already supports. No response models, no new operations, no new types beyond what is needed to describe the current surface.

What changed

• gettyimages-api.d.ts — a single root declaration covering the client, the fourteen request classes, and the GettyApiRequest base.
• package.json — adds "types", a test:types script, and typescript plus @types/node as dev dependencies.
• types-test.ts and tsconfig.types.json — a compile-time test, run by npm run test:types.
• .github/workflows/lint.yml — a types job so the check runs on every pull request.
• .npmignore, .eslintignore, README.md — housekeeping for the new files.

No changes to lib/ or gettyimages-api.js.

Backwards compatibility

Declaration files are erased at runtime and no runtime code moved, so JavaScript consumers cannot be affected.

The risk that does exist is a declaration that is too strict and rejects a call the SDK accepts. For anyone currently on dts-gen output, that would turn working code into a compile error. Three findings from reading the implementation against the tests shaped the signatures:

1. Singular builders accept arrays. withCollectionCode, withFileType, withResponseField and others are named in the singular, but the tests call them with arrays such as withCollectionCode(["WRI", "ARF"]). The implementation appends the whole array and addParameter joins it. These are typed string | string[].
2. Identifier builders accept numbers. The tests use withKeywordId([1234, 5678]), withEntityUris([123, 456]) and withProductId(5678), while other call sites pass strings. These are typed string | number | Array<string | number>.
3. execute() returns Promise<any>. The SDK returns raw parsed JSON and defines no response models. Promise<unknown> would force every consumer to cast before reading response.images[0], which the README does throughout.

The entry point uses export = GettyImagesApi, matching the CommonJS module.exports =, so both import api from "gettyimages-api" and require keep working.

Verification

• npm test — 165 tests pass, unchanged.
• npm run test:types — passes under strict.
• npm run lint — clean.
• npm pack --dry-run — the .d.ts ships; the test harness does not.
• Negative checks confirm the type test has teeth. Narrowing withCollectionCode to string, narrowing withKeywordId to string, switching execute() to Promise<unknown>, and switching to export default each fail the build.
• Consumer smoke test: packed the tarball, installed it into a scratch TypeScript project, and confirmed a fluent chain and the token round-trip compile, and that genuine mistakes are still caught rather than degrading to any.

🤖 Generated with Claude Code

[coveralls]

coverage: 98.093%. remained the same — feature/typescript-declarations into main