@dsptch-work/api-client 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -5,6 +5,275 @@ All notable changes to `@dsptch-work/api-client` are documented here. The format
 [Semantic Versioning](https://semver.org) — currently `0.x`, so breaking changes may land in a
 minor bump until `1.0.0`. See [RELEASING.md](./RELEASING.md) for the release and versioning process.
 
+## [0.38.0] - 2026-10-15
+
+### Added
+
+- New class `ProjectUserVisibilities`: `listUserVisibilities()`, `getUserVisibility()`,
+  `createUserVisibility()`, and `deleteUserVisibility()`, with operation types and Zod schemas.
+  Supply `path: { project_id }` for list/create and `path: { project_id, id }` for get/delete;
+  `id` is the visibility join ID. `ProjectUserVisibilityParameters` requires `user_id`, and
+  `ProjectUserVisibilityResponseObject` returns the join ID, project ID, user ID, and timestamps.
+  Grant `projects.user_visibilities:read`, `:create`, or `:delete` as appropriate. Access requires
+  the restricting owner's company key or a user key the owner issued to one of its admins;
+  the named user must be a manager, safety manager, or field lead of the owner. Other callers
+  that can read the project get an empty list, `404` on get/delete, and `403` on create. This
+  also applies to the owner's keys when visibility is not restricted. There is no update
+  method; deletion returns `204` with no body and preserves descendant projects' visibility rows.
+- `FormSubmissionResponseObject` and `zFormSubmissionResponseObject` add required `id` to the
+  detail returned by `Forms.getFormSubmission()`. Add it to typed fixtures and custom validators.
+- `FormDefinitionObject` and `zFormDefinitionObject` add required `submission_shape` to
+  `Forms.listFormDefinitions()` / `getFormDefinition()` responses. It describes the answers as an OpenAPI 3.0
+  schema, including object properties, array items, and choice descriptions; unanswered fields
+  may be absent or null. The generated type is `{ [key: string]: unknown }`, so narrow the
+  schema before inspecting it. Add the field to typed fixtures. File, signature, and matrix
+  questions are omitted, so the shape does not cover every submission field.
+
+### Changed
+
+- **Breaking:** `ProductionJobScopePriceParameters`, `ProductionJobScopePriceUpdateParameters`,
+  and `ProductionJobScopePriceResponseObject` replace `unit_price` with `unit_price_cents`,
+  including their Zod schemas. Update `ProductionJobScopePrices.createJobScopePrice()` /
+  `updateJobScopePrice()` calls and read consumers. Send nonnegative decimal-string cents:
+  `'120000'` replaces the former dollar amount `'1200'`; fractional cents such as `'3.5'`
+  remain exact. The retired name returns `400 unknown_key`; JSON numbers and negative prices
+  return `422`. Price fields remain omitted for users without financial access.
+- **Breaking at runtime:** `TimeEntries.createTimeEntry()` / `updateTimeEntry()` now require
+  explicit UTC offsets in `start_time` and `end_time`. Offset-free values, previously interpreted
+  in the pay schedule's time zone, now return `422 invalid_date`. Send `Z` or a numeric offset
+  such as `-04:00`; use the desired offset to select either occurrence of a repeated daylight
+  saving time. `TimeEntryCreateParameters` / `TimeEntryUpdateParameters` still use strings, so
+  TypeScript alone cannot catch missing offsets.
+- **Breaking at runtime:** timestamp `filter[...][gte]` / `[lte]` bounds and `as_of[valid]` /
+  `as_of[transaction]` coordinates now require an explicit UTC offset. Date-only or offset-free
+  values return `422`; send `'2026-10-15T00:00:00Z'` for midnight UTC. Calendar-date filters
+  still accept date-only bounds. Generated query fields remain strings.
+- **Breaking:** `TimecodeParameters`, `TimecodeGenesisParameters`, and
+  `TimecodeScheduledChangeParameters` now describe `effective_date` as a calendar date.
+  Send `'2026-10-15'` through `Timecodes.createTimecode()`, `shiftTimecodeGenesis()`, or
+  `scheduleTimecodeChange()`; a value containing a time of day returns `422`. The day starts
+  at midnight UTC, except that a scheduled change on the timecode's first day starts at its
+  existing beginning. The three corresponding Zod schemas now validate ISO dates.
+  `TimecodeCorrectionParameters.effective_from` / `effective_to`, used by
+  `Timecodes.updateTimecode()`, instead require date-times with explicit offsets; offset-free
+  bounds return `422 invalid_date`.
+- **Breaking validation:** `zTimeEntryCreateParameters`, `zTimeEntryUpdateParameters`, and
+  `zTimecodeCorrectionParameters` now validate ISO date-times. These generated validators
+  accept UTC `Z` strings and reject numeric offsets, although the API accepts either; normalize
+  offset-bearing timestamps to UTC `Z` before validating them with these schemas.
+- **Breaking at runtime:** `Users.updateUser()` returns `422` with field pointers when changing
+  an already verified `email`, `personal_email`, or `phone_number`, instead of silently keeping
+  the old value. Omit verified contacts or resend their current values; changes require the
+  user's confirmation. `UserUpdateParameters` is unchanged.
+- **Breaking:** `AssetsItemParameters.purchase_date`, `AssetsItemUpdateParameters.purchase_date`,
+  and `ComplianceCheckParameters.time_due` now accept calendar dates, without a time of day.
+  Send `'2026-10-15'` through `AssetsItems.createItem()` / `updateItem()` or
+  `ComplianceChecks.updateCheck()`; timestamps now return `422`. Null clears the date and
+  omission retains it on update. The corresponding Zod schemas now validate ISO dates, while
+  the TypeScript fields remain `string | null`. Asset purchase-date responses remain nullable
+  ISO date-time strings; use their calendar date rather than echoing the full timestamp on write.
+- **Breaking at runtime:** date parsing now rejects impossible calendar dates such as
+  `'2026-02-30'` with `422`, rather than rolling them into the next month.
+  Correct invalid date or timestamp values in bodies, date filters, and `as_of` coordinates;
+  method signatures are unchanged.
+- **Breaking error handling:** `AssetsProducts.createProduct()` now returns `400 parameter_missing`
+  with pointer `#/type` when `type` is omitted, and `422 validation_failed` with that pointer
+  for an unsupported value or wrong JSON type. `AssetsItems.createItem()` / `updateItem()`
+  return `404`, rather than `422`, for an unknown or inaccessible newly assigned
+  `assets_product_id`. Handle these statuses through the existing generated error unions.
+
+### Fixed
+
+- `AssetsFormAssignmentTriggers.createFormAssignmentTrigger()` / `updateFormAssignmentTrigger()`
+  now consistently store `assigned_user_ids: []` unless `assign_to` is `'custom'`, including
+  updates that omit `assign_to`. Supplied user IDs are checked before clearing them; an unseen
+  user returns `404` even for another assignment mode. The generated parameter types are unchanged.
+- `AssetsFormAssignmentTriggers` writes now retain the requested `time_of_day_due` when a time
+  in the skipped hour is saved on the time zone's spring daylight saving transition day, rather than
+  permanently shifting the recurring due time forward an hour. Existing saved times and method
+  signatures are unchanged.
+- `PwaTrades.createMerge()` now points a self-merge or different-owner refusal at
+  `#/target_trade_id`, and `People.createEmploymentScheduledChange()` points a refused
+  current/past change to an older segment at `#/effective_date`. Both remain
+  `422 validation_failed`; use `Problem.errors` to associate the error with the input.
+- Conflicting placement fields in `AssetsItems.createItem()` now return `422 validation_failed`
+  with a pointer for every supplied placement field. Unseen placement sites, users, and containers
+  return `404`, including a former employee without a current role. Method signatures are unchanged.
+
+See the [API changelog](https://dsptch.app/support/docs/developers/api-changelog#2026-10-15) for the
+complete REST contract details and error behavior.
+
+## [0.37.0] - 2026-10-14
+
+### Added
+
+- `Jobs` adds `listJobDocuments()`, `createJobDocument()`, `getJobDocument()`,
+  `updateJobDocument()`, and `deleteJobDocument()`, with corresponding operation types and Zod
+  schemas. Use `path: { job_id }` for list/create and `path: { job_id, id }` for the others.
+  `JobDocumentParameters` and `JobDocumentUpdateParameters` support an external `url` or an
+  uploaded `file`; supply exactly one source on create and retain exactly one after an update.
+  Although create's generated fields are optional, the server requires nonblank `type` and `name`.
+  Register files through `DirectUploads.createDirectUpload()` with
+  `DirectUploadParameters.resource: 'jobs.documents'`, then send its signed ID as `file`.
+  `JobDocumentResponseObject` exposes nullable `url` and `file` download metadata;
+  `JobDocumentsResponseObject` wraps the list, and `ListJobDocumentsData.query` accepts
+  `'filter[type]'`. PWA documents are always `admin_only`; callers without job financial access
+  cannot read them. Grant the appropriate `jobs.documents:read` / `:create` / `:update` / `:delete`
+  scope. Deletion resolves `204` with no body.
+- `PositionParameters.pay_rates_rule_package_id` accepts a nullable package ID through
+  `Jobs.createPosition()` / `updatePosition()`. Choose a selectable package belonging to the path
+  job; an inaccessible, hidden, or other-job package returns `404`. Omit it on create to leave the
+  assignment unset, omit it on update to retain it, or send null to clear it. A cash-fringe package
+  on a non-PWA position returns `422`.
+- `SiteCheckInResponseObject` and `zSiteCheckInResponseObject` add required nullable
+  `duration_minutes`, the elapsed whole minutes between check-in and check-out, rounded to the nearest minute. It is null until the
+  visitor checks out. Add the field to typed fixtures for `OversiteSiteCheckIns` reads.
+- `TodoInboxTodoResponseObject` and `zTodoInboxTodoResponseObject` add required `priority`
+  (`'critical' | 'high' | 'medium' | 'low' | null`) and `category` (the same ten categories used by
+  compliance checks). `Todos.listTodoInbox()` now carries them on `kind: 'todo'` entries;
+  add both fields to typed fixtures. These are read fields, without new SDK write methods or
+  query filters.
+
+### Changed
+
+- **Breaking:** `UserParameters`, `UserCompanyCreateParameters`,
+  `UserCompanyScheduledChangesParameters`, `UserCompanyScheduledChange`, and `UserResponseObject`
+  replace `hourly_rate`, `training_annual_amount`, `employer_combined_health_amount`, and
+  `employer_combined_savings` with the corresponding `_cents` fields. Update calls to
+  `Users.createUser()`, `createCompany()`, `createUserCompanyScheduledChange()`, and
+  `updateScheduledChange()` and consumers of user and scheduled-change responses. Send decimal
+  strings in cents: `hourly_rate_cents: '3250'` replaces `hourly_rate: '32.50'`.
+  Response values are decimal-string cents such as `'3250.0'`, without a currency symbol;
+  obtain the currency from `People.getEmployment()`. Omitted amounts remain unset on create
+  or unchanged on scheduled updates, null clears them, and `'0'` sets zero. Old dollar-field
+  names return `400 unknown_key`; corresponding Zod schemas now expose only the cents names.
+- **Breaking:** `ProjectParameters` and `ProjectUpdateParameters` replace `budget` with
+  `budget_cents` for `Projects.createProject()` / `updateProject()`, including their Zod schemas.
+  Send `'123450'` for a budget of $1,234.50, rather than the former dollar string `'1234.50'`.
+  Null clears it and omission retains it on update. `budget` now returns `400 unknown_key`.
+  A budget, including null, still returns `422` while federal PWA tracking is off.
+  `ProjectResponseObject.budget_cents` and `budget_currency` are now optional nullable fields:
+  handle their absence when the caller cannot see project financials instead of assuming null.
+- **Breaking:** `ApprenticeshipWageScheduleParameters` / `ApprenticeshipWageScheduleUpdateParameters`
+  make `journeyworker_wage_cents`, `journeyworker_fringe_cents`, and `end_wage_cents` decimal
+  strings. `ApprenticeshipWageSchedulePeriodParameters` /
+  `ApprenticeshipWageSchedulePeriodUpdateParameters`, including nested `periods_attributes`,
+  likewise make `wage_cents`, `fringe_cents`, `wage_percent`, and `fringe_percent` strings.
+  Update the `ApprenticeshipWageSchedules` and `ApprenticeshipWageSchedulePeriods` write calls
+  to send `'2800.5'` cents or `'62.5'` percent, or echo the string from a read. JSON numbers
+  now return `422` at the field pointer; nullable fringe fields still accept null.
+  The corresponding Zod schemas enforce nonnegative decimal strings.
+- **Breaking:** `AssetsItemParameters.purchase_price_cents` and
+  `AssetsItemUpdateParameters.purchase_price_cents` change from `number | null` to
+  `string | null` for `AssetsItems.createItem()` / `updateItem()`. Send `'2800'` or `'2800.5'`,
+  or null to clear it. JSON numbers now return `422`; the corresponding Zod schemas enforce
+  nonnegative decimal strings. Purchase-price storage rounds beyond two decimal places in cents.
+- **Breaking:** `PositionParameters` now requires decimal strings for `cash_fringe_rate_cents`,
+  `hourly_rate_cents`, `pwa_wage_pay_rate_cents`, and `wage_adder_rate_cents` in
+  `Jobs.createPosition()` / `updatePosition()`. `start_time` / `end_time` no longer accept null;
+  supply real `YYYY-MM-DD` dates or omit the keys to retain dates on update or leave a new
+  position unscheduled. A supplied `pwa_details_attributes` object requires
+  `skill_level: 'journeyman' | 'foreman' | null`; use `{ skill_level: null }` rather than `{}`.
+  Send `pwa` as a boolean and nonblank string IDs, using null to clear nullable references.
+  Use `zPositionParameters` to validate these forms locally.
+- **Breaking:** `UserParameters` now types `enrolled_in_t_and_a` and `overtime_eligible` as
+  booleans, and `worked_annual_minutes`, `pto_annual_minutes`, `holiday_annual_minutes`, and
+  `training_annual_minutes` as nullable numbers instead of strings. Send whole-minute integers
+  and real booleans through `Users.createUser()`. `roles` no longer accepts null; omit it or
+  send `[]` to grant no roles, and send unique nonblank role strings. `company_user_pwa_info`
+  must be an object when supplied, without null. `zUserParameters` also checks nonblank names
+  and IDs and a date-only nullable `birth_date`. The old contact union is removed from the
+  generated type and schema, but the server still requires an email or phone unless
+  `skip_invite: true`; missing names return `400`, and invalid values return `422` with pointers.
+  Optional nullable profile fields now match accepted nulls. Omitted or null pay amounts now
+  remain unset rather than becoming zero. Send explicit '0' to designate zero: an unset
+  `training_annual_amount_cents` can fail the PWA designation check, and an unset
+  `hourly_rate_cents` can cause aggregate imports to return `HOURLY_RATE_NOT_FOUND` when no
+  position rate exists.
+- **Breaking:** `JobCreateParameters` and `JobUpdateParameters` are standalone objects.
+  `created_by_user_id` is optional in the create type so template copies can inherit it; plain
+  creates still need a creator and requesting company. Job feature-allocation flags,
+  `job_work_types_attributes`, `job_address_attributes`, and address `verified` no longer accept
+  null; omit them to retain current values. `region` now accepts null.
+  `time_card_start_day` is a number, with `zJobCreateParameters` / `zJobUpdateParameters`
+  requiring an integer from 0 through 6. `Jobs.createJob()` / `updateJob()` now refuse wrong
+  JSON types and malformed nested fields with `422` pointers. Send lowercase PWA mode keys
+  (`'all'`, `'pw_only'`, `'ap_only'`, `'none'`), booleans for flags, nonblank IDs, and declared
+  nested keys. Null can still clear nullable schedule dates and references.
+- **Breaking:** monetary write Zod schemas now reject malformed strings before submission,
+  matching server-side `422 validation_failed` errors with exact field pointers. Use plain
+  decimal strings with digits before the decimal point; blanks, whitespace, currency symbols,
+  scientific notation, and values such as `'.5'` are refused. This applies to employment pay,
+  time-entry and position rates, wage determinations, per diems, payroll amounts, project
+  budgets, asset prices, and production scope prices. Most values must be nonnegative;
+  `PaystubLineItemParameters.amount_cents` and `PositionParameters.pwa_wage_pay_rate_cents`
+  allow a leading minus. `RateRuleEffect.amount_cents` requires nonnegative whole-cent strings
+  such as `'300'`, without a decimal part. Handle these refusals through `Problem.errors`.
+- **Breaking:** `PaystubLineItems.createPaystubLineItem()` / `updatePaystubLineItem()` enforce
+  the documented string `amount_cents`, nonblank reference IDs, and lowercase
+  `contributor: 'employee' | 'employer'`. JSON-number amounts now return `422`, and omitting any
+  of create's four required fields returns `400 parameter_missing`. Send decimal-string cents;
+  negative and fractional amounts remain supported. `zPaystubLineItemParameters` /
+  `zPaystubLineItemUpdateParameters` now validate the ID and money patterns.
+- **Breaking:** `Users.createUser()`, `createCompany()`, `updateCompany()`,
+  `People.createEmployment()`, and `updateEmployment()` return `404` for a newly assigned
+  `manager_user_id` outside the key's visible people. Choose a visible manager. Employment
+  updates can still omit or resend an already held legacy manager; method signatures are unchanged.
+- **Breaking:** `Users.removeUserFromCompany()` now requires
+  `headers: { 'If-Match': etag }` in `RemoveUserFromCompanyData`. Read the employment ID from
+  `UserResponseObject.employment_id`, then obtain its validator through
+  `People.listEmploymentHistory()` or, while a version covers now, `People.getEmployment()`.
+  A key without those read scopes may send `'*'` to delete whatever state exists.
+  `RemoveUserFromCompanyErrors` adds `412` and `428`: re-read after a stale validator and add
+  the header when it is missing. Success remains `200` with the user body.
+- **Breaking at runtime:** `TimeEntries.createTimeEntry()` / `updateTimeEntry()` now interpret
+  `start_time` / `end_time` without an offset in the time card's pay schedule zone. If you mean
+  UTC, append `Z`; explicit `Z` or `±HH:MM` values retain their prior meaning. A bare date-time
+  now represents local wall time, including DST resolution and pay-period edge validation.
+  Request types remain strings, so TypeScript cannot catch a missing offset.
+- **Breaking:** `CompetenciesAssessmentCriteria.listAssessmentCriteria()` /
+  `getAssessmentCriterion()` replace the assessment key-activity read methods. The new
+  `CompetencyAssessmentCriterionResponseObject` uses `competencies_criterion_id`.
+  `CompetenciesEvidenceItems.listEvidenceItems()` / `getEvidenceItem()` keep their method names
+  but replace `path.key_activity_id` with `path.criterion_id`; evidence responses replace
+  `competencies_assessment_key_activity_id` with `competencies_assessment_criterion_id`.
+  Grant `competencies.assessments.criteria:read` and
+  `competencies.assessments.criteria.evidence_items:read` in place of the retired key-activity
+  scopes. These reads remain available to companies with Competencies enabled.
+  `CompetencyCriterionParameters` / `CompetencyCriterionResponseObject` replace nullable
+  `assessment_method` with nonnullable `assessment_methods`, an array of the same eight method
+  values. Use `[]` for no suggested methods; corresponding Zod schemas follow the new shapes.
+
+### Removed
+
+- **Breaking:** `JobParameters` and `zJobParameters` are removed. Import
+  `JobCreateParameters` / `zJobCreateParameters` or `JobUpdateParameters` /
+  `zJobUpdateParameters` for the owning write.
+- **Breaking:** `PositionParameters.per_diem_rate_cents` is removed, including from
+  `zPositionParameters`; sending it now returns `400 unknown_key`. Select `per_diem_id`
+  instead, since the rate comes from that per diem.
+- **Breaking:** `CompetenciesAssessmentKeyActivities`,
+  `CompetencyAssessmentKeyActivityResponseObject`, `ListAssessmentKeyActivities*`,
+  `GetAssessmentKeyActivity*`, and their corresponding Zod exports are removed. Migrate to
+  `CompetenciesAssessmentCriteria`, `CompetencyAssessmentCriterionResponseObject`,
+  `ListAssessmentCriteria*`, and `GetAssessmentCriterion*`.
+- **Breaking:** `ProblemTypeCatalog` and `zProblemTypeCatalog` remove `non_numeric_cents`.
+  Delete that case from exhaustive switches and handle malformed money as `validation_failed`
+  with field pointers instead.
+
+### Fixed
+
+- **Breaking response correction:** `AssetsItems.deleteDocument()` now resolves `204`
+  with no body. `DeleteDocumentResponses` replaces its `200: AssetsDocumentResponseObject`
+  arm with `204: void`, and `zDeleteDocumentResponse` validates void. Remove code that reads
+  the deleted document from the response; read it before deletion if needed.
+- `DirectUploads.createDirectUpload()` now stores `resource: 'assets.items.documents'` uploads
+  on protected storage, matching the asset document attachment. Request and response types
+  stay unchanged; continue attaching the returned purpose-bound signed ID to an asset document.
+
+See the [API changelog](https://dsptch.app/support/docs/developers/api-changelog#2026-10-14) for the
+complete REST contract details and error behavior.
+
 ## [0.36.0] - 2026-10-13
 
 ### Added