test: add validation tests for all resources and contributing guide

- Add test suites for expenses, projects, clients, contacts, tasks,
  users, and reports resources (was only time-entries, invoices, outcomes)
- Add client instantiation tests verifying all resources are wired up
- Add public API export validation tests (Keito, errors, OutcomeTypes, VERSION)
- Add agentSummary blended reporting tests (time + outcomes + empty + failures)
- Add CONTRIBUTING.md with development setup, conventional commits guide,
  testing conventions, PR process, and release process docs
- Test count: 33 → 58 across 14 test files

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sionsmith

CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# Contributing to @keito-ai/sdk
+
+Thanks for your interest in contributing! This guide covers everything you need to get started.
+
+## Table of Contents
+
+- [Before You Start](#before-you-start)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Code Style](#code-style)
+- [Conventional Commits](#conventional-commits)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Adding a New Resource](#adding-a-new-resource)
+- [Regenerating Types](#regenerating-types)
+- [Release Process](#release-process)
+
+## Before You Start
+
+- Check [open issues](https://github.com/osodevops/keito-node/issues) before starting work — someone may already be on it.
+- For large changes, open an issue first to discuss the approach.
+- All contributions are released under the [MIT License](LICENSE).
+
+## Development Setup
+
+**Prerequisites:** Node.js 18+, npm
+
+```bash
+# Clone the repo
+git clone https://github.com/osodevops/keito-node.git
+cd keito-node
+
+# Install dependencies
+npm install
+
+# Generate types from OpenAPI spec
+npm run generate
+
+# Run the full validation pipeline
+npm run typecheck
+npm test
+npm run build
+```
+
+### Development Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run generate` | Regenerate types from the OpenAPI spec |
+| `npm run typecheck` | Run TypeScript type checking |
+| `npm test` | Run all tests with Vitest |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run build` | Build ESM + CJS output to `dist/` |
+
+## Project Structure
+
+```
+src/
+  index.ts              # Public exports — everything users import
+  client.ts             # Keito class — wires resources to HTTP client
+  version.ts            # SDK version constant
+  core/
+    http.ts             # Fetch wrapper, retries, auth, timeout
+    errors.ts           # Typed error hierarchy
+    pagination.ts       # Auto-pagination iterator
+  generated/
+    openapi.d.ts        # AUTO-GENERATED — do not edit by hand
+    models.ts           # Re-export aliases for generated schema types
+  resources/
+    time-entries.ts     # One file per API resource
+    expenses.ts
+    ...
+  outcome-types.ts      # OutcomeTypes constants (F8)
+tests/
+  client.test.ts        # Client instantiation tests
+  index.test.ts         # Public API export validation
+  core/
+    http.test.ts        # HTTP client tests (retries, errors, timeouts)
+    pagination.test.ts  # Pagination iterator tests
+  resources/
+    *.test.ts           # One test file per resource
+```
+
+### What's auto-generated vs hand-written
+
+| Layer | Source | Changes when... |
+|-------|--------|----------------|
+| `src/generated/openapi.d.ts` | Auto-generated by `openapi-typescript` | Any spec field/schema changes |
+| `src/generated/models.ts` | Hand-written re-exports | New schemas added to spec |
+| `src/core/*` | Hand-written | Rarely (stable infrastructure) |
+| `src/resources/*` | Hand-written, referencing generated types | New endpoints added to spec |
+
+**Never edit `src/generated/openapi.d.ts` by hand.** Run `npm run generate` instead.
+
+## Code Style
+
+- **TypeScript strict mode** — no `any`, no implicit returns, no unused variables.
+- **Snake_case for API fields** — matches the API. No camelCase transformation.
+- **`const` over `let`** — use `let` only when reassignment is necessary.
+- **Explicit return types** on public methods.
+- **No runtime dependencies** — the SDK uses only native `fetch`. Keep it that way.
+- **Arrays as `T[]`** not `Array<T>`.
+- **Interfaces for public params** — use `interface` for method parameter types (e.g. `ListTimeEntriesParams`), `type` for aliases.
+
+## Conventional Commits
+
+All commit messages **must** follow the [Conventional Commits](https://www.conventionalcommits.org/) format. This drives automatic versioning and changelog generation via release-please.
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Commit Types
+
+| Type | Description | Version bump |
+|------|-------------|-------------|
+| `feat` | New feature | Minor (0.x: patch) |
+| `fix` | Bug fix | Patch |
+| `docs` | Documentation only | None |
+| `test` | Adding or updating tests | None |
+| `chore` | Maintenance (CI, deps, config) | None |
+| `refactor` | Code change that neither fixes a bug nor adds a feature | None |
+| `perf` | Performance improvement | Patch |
+
+### Examples
+
+```
+feat: add client.contacts.update() method
+fix: handle empty metadata in pagination response
+test: add validation tests for reports resource
+docs: update README with outcome billing examples
+chore: bump openapi-typescript to v8
+feat!: rename OutcomeLogParams.source to OutcomeLogParams.entry_source
+
+BREAKING CHANGE: OutcomeLogParams.source has been renamed to entry_source
+```
+
+A `BREAKING CHANGE` footer or `!` after the type triggers a major version bump (or minor while on 0.x).
+
+## Testing
+
+Every resource and core module must have tests. We use [Vitest](https://vitest.dev/).
+
+### Test conventions
+
+- **Mock `globalThis.fetch`** — tests never make real HTTP calls.
+- **One test file per source file** — `src/resources/expenses.ts` -> `tests/resources/expenses.test.ts`.
+- **Test what the SDK sends** — verify the correct HTTP method, URL, query params, and request body.
+- **Test return values** — verify the response is correctly parsed and returned.
+- **Use `afterEach(() => vi.restoreAllMocks())`** — always clean up mocks.
+
+### Running tests
+
+```bash
+# Run all tests
+npm test
+
+# Run in watch mode during development
+npm run test:watch
+
+# Run a specific test file
+npx vitest run tests/resources/expenses.test.ts
+```
+
+### Validation checklist
+
+Before submitting a PR, ensure all of these pass:
+
+```bash
+npm run generate    # types regenerate without errors
+npm run typecheck   # no TypeScript errors
+npm test            # all tests pass
+npm run build       # produces dist/ without errors
+```
+
+## Pull Request Process
+
+1. **Branch from `main`**: name your branch `feat/description`, `fix/description`, or `test/description`.
+2. **Write tests**: every new feature or bug fix needs tests.
+3. **Run the full pipeline**: `npm run generate && npm run typecheck && npm test && npm run build`.
+4. **Commit with conventional commits**: your PR title should also follow the format.
+5. **Keep PRs focused**: one logical change per PR. Split large changes into smaller PRs.
+6. **Link related issues**: use `closes #123` in the PR body.
+
+### PR checklist
+
+- [ ] Tests pass (`npm test`)
+- [ ] Type checking passes (`npm run typecheck`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] Commit messages follow conventional commits
+- [ ] New public API surface is exported from `src/index.ts`
+- [ ] New resource has a corresponding test file
+
+## Adding a New Resource
+
+When a new endpoint is added to the OpenAPI spec:
+
+1. **Regenerate types**: `npm run generate`
+2. **Add re-exports** to `src/generated/models.ts` for any new schemas.
+3. **Create the resource file** at `src/resources/<resource-name>.ts`:
+
+```typescript
+import type { HttpClient } from '../core/http.js';
+import { paginate, PaginatedResponse } from '../core/pagination.js';
+import type { NewModel } from '../generated/models.js';
+
+export interface ListNewModelsParams {
+  page?: number;
+  per_page?: number;
+  // ... filters from the spec
+}
+
+export class NewModels {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(params: ListNewModelsParams = {}): Promise<PaginatedResponse<NewModel>> {
+    return paginate<NewModel>(this.http, '/api/v2/new_models', 'new_models', params);
+  }
+}
+```
+
+4. **Wire it up** in `src/client.ts` — add as a `readonly` property.
+5. **Export types** from `src/index.ts`.
+6. **Write tests** in `tests/resources/<resource-name>.test.ts`.
+7. **Run the full pipeline** to verify.
+
+## Regenerating Types
+
+The SDK types are auto-generated from the [Keito OpenAPI v2 spec](openapi/openapi-v2.yaml).
+
+### Locally
+
+```bash
+# Update the spec file in openapi/openapi-v2.yaml, then:
+npm run generate
+npm run typecheck
+```
+
+### Via CI
+
+The `generate.yml` workflow can be triggered manually or via `repository_dispatch` from the keito repo. It fetches the latest spec, regenerates types, and opens a PR if anything changed.
+
+## Release Process
+
+Releases are fully automated via [release-please](https://github.com/googleapis/release-please).
+
+### How it works
+
+1. Merge PRs with conventional commit messages to `main`.
+2. Release-please opens a "Release PR" that bumps `package.json`, updates `CHANGELOG.md`, and updates `.release-please-manifest.json`.
+3. When the Release PR is merged, release-please creates a git tag and GitHub Release.
+4. The publish job in `release-please.yml` builds and publishes to npm.
+
+**You don't need to manually bump versions, create tags, or publish.** Just write good commit messages and merge.
+
+### Manual release (emergency)
+
+If you need to release outside the normal flow:
+
+```bash
+# Update version in package.json and src/version.ts
+npm version patch  # or minor, major
+git push --follow-tags
+```
+
+The `release-please.yml` workflow will detect the tag and publish.

tests/client.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { Keito } from '../src/client.js';
+import { TimeEntries } from '../src/resources/time-entries.js';
+import { Expenses } from '../src/resources/expenses.js';
+import { Projects } from '../src/resources/projects.js';
+import { Clients } from '../src/resources/clients.js';
+import { Contacts } from '../src/resources/contacts.js';
+import { Tasks } from '../src/resources/tasks.js';
+import { Users } from '../src/resources/users.js';
+import { Invoices, InvoiceMessages } from '../src/resources/invoices.js';
+import { Reports } from '../src/resources/reports.js';
+import { Outcomes } from '../src/resources/outcomes.js';
+
+describe('Keito client', () => {
+  it('exposes all resource instances', () => {
+    const client = new Keito({ apiKey: 'kto_test', accountId: 'acc_test' });
+
+    expect(client.timeEntries).toBeInstanceOf(TimeEntries);
+    expect(client.expenses).toBeInstanceOf(Expenses);
+    expect(client.projects).toBeInstanceOf(Projects);
+    expect(client.clients).toBeInstanceOf(Clients);
+    expect(client.contacts).toBeInstanceOf(Contacts);
+    expect(client.tasks).toBeInstanceOf(Tasks);
+    expect(client.users).toBeInstanceOf(Users);
+    expect(client.invoices).toBeInstanceOf(Invoices);
+    expect(client.invoices.messages).toBeInstanceOf(InvoiceMessages);
+    expect(client.reports).toBeInstanceOf(Reports);
+    expect(client.outcomes).toBeInstanceOf(Outcomes);
+  });
+
+  it('uses default baseUrl when not provided', () => {
+    const client = new Keito({ apiKey: 'kto_test', accountId: 'acc_test' });
+
+    // All resources should be initialized — verifies constructor doesn't throw
+    expect(client.timeEntries).toBeDefined();
+    expect(client.outcomes).toBeDefined();
+  });
+});

tests/index.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import * as sdk from '../src/index.js';
+
+describe('Public API exports', () => {
+  it('exports the Keito client class', () => {
+    expect(sdk.Keito).toBeDefined();
+    expect(typeof sdk.Keito).toBe('function');
+  });
+
+  it('exports error classes', () => {
+    expect(sdk.KeitoError).toBeDefined();
+    expect(sdk.KeitoApiError).toBeDefined();
+    expect(sdk.KeitoAuthError).toBeDefined();
+    expect(sdk.KeitoForbiddenError).toBeDefined();
+    expect(sdk.KeitoNotFoundError).toBeDefined();
+    expect(sdk.KeitoConflictError).toBeDefined();
+    expect(sdk.KeitoRateLimitError).toBeDefined();
+    expect(sdk.KeitoTimeoutError).toBeDefined();
+    expect(sdk.KeitoConnectionError).toBeDefined();
+  });
+
+  it('exports PaginatedResponse', () => {
+    expect(sdk.PaginatedResponse).toBeDefined();
+    expect(typeof sdk.PaginatedResponse).toBe('function');
+  });
+
+  it('exports OutcomeTypes constants', () => {
+    expect(sdk.OutcomeTypes).toBeDefined();
+    expect(sdk.OutcomeTypes.TICKET_RESOLVED).toBe('ticket_resolved');
+    expect(sdk.OutcomeTypes.LEAD_QUALIFIED).toBe('lead_qualified');
+    expect(sdk.OutcomeTypes.MEETING_BOOKED).toBe('meeting_booked');
+    expect(sdk.OutcomeTypes.DOCUMENT_GENERATED).toBe('document_generated');
+    expect(sdk.OutcomeTypes.CODE_REVIEW_COMPLETED).toBe('code_review_completed');
+    expect(sdk.OutcomeTypes.DATA_PROCESSED).toBe('data_processed');
+    expect(sdk.OutcomeTypes.EMAIL_SENT).toBe('email_sent');
+    expect(sdk.OutcomeTypes.INVOICE_CREATED).toBe('invoice_created');
+    expect(sdk.OutcomeTypes.WORKFLOW_COMPLETED).toBe('workflow_completed');
+    expect(sdk.OutcomeTypes.CUSTOM).toBe('custom');
+  });
+
+  it('exports VERSION', () => {
+    expect(sdk.VERSION).toBeDefined();
+    expect(typeof sdk.VERSION).toBe('string');
+    expect(sdk.VERSION).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});