@dsptch-work/api-client 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -5,6 +5,260 @@ 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.36.0] - 2026-10-13
+
+### Added
+
+- New class `ProjectDocuments`: `listProjectDocuments()`, `createProjectDocument()`,
+  `getProjectDocument()`, `updateProjectDocument()`, `deleteProjectDocument()`, and
+  `listProjectDocumentVersions()`. `ProjectDocumentParameters` requires `file` and
+  `performed_by_user_id`; get the signed file id through `DirectUploads.createDirectUpload()`
+  with `DirectUploadParameters.resource: 'projects.documents'`. `ProjectDocumentUpdateParameters`
+  accepts an optional replacement file and nullable `filename` / `description`.
+  `ProjectDocumentResponseObject.file` is nullable and exposes download metadata and `url`.
+  `ProjectDocumentVersionResponseObject` records audit events (`'create' | 'update' | 'destroy'`),
+  actor, and timestamp. List methods support cursor pagination; documents also support created/updated
+  date filters. Grant the appropriate `projects.documents:read` / `:create` / `:update` / `:delete`
+  scopes and `projects.documents.versions:read` for history. Corresponding operation types and Zod
+  schemas are exported.
+- `PayPeriods.getPayPeriod()` reads an individual period with `path: { id }` and the existing
+  `pay_periods:read` scope. New `PayPeriodResponseObject` and `zPayPeriodResponseObject` are shared
+  by show and list responses. `ListPayPeriodsData.query` adds
+  `'filter[timekeeping_pay_period_config_id]'` to select a pay schedule family; use the same id each
+  period returns as `timekeeping_pay_period_config_id`.
+- `ListEmploymentsData.query` adds `'filter[companies_department_id]'`. It selects the department
+  in the employment version at now or the supplied `'as_of[valid]'` time, so historical queries
+  follow historical assignments.
+
+### Changed
+
+- **Breaking:** `TimeEntryCreateParameters` is now a standalone object requiring
+  `timekeeping_time_card_id`, `start_time`, and `end_time` for
+  `TimeEntries.createTimeEntry()`. `TimeEntryUpdateParameters` keeps every field optional for
+  `updateTimeEntry()`. Both make `feature_ids` a nonnullable array; create's
+  `feature_allocation_acknowledged` and update's `confirm_allocation_conflict` accept booleans only.
+  Pass `[]` to clear feature allocations and omit the field to retain them on update. The generated
+  Zod schemas validate the split objects and required create timestamps; timestamp strings are
+  parsed by the server rather than restricted to Zod's ISO date-time format. Missing required
+  fields return `400`; wrong JSON types return `422` with field pointers, and unparseable timestamp
+  strings return `422 invalid_date`. Correct the values before retrying.
+- **Breaking:** `Users.updateCompany()` and `removeUserFromCompany()` take
+  `path: { user_id, id }` rather than `path: { user_id, company_id }`.
+  Update `UpdateCompanyData` / `RemoveUserFromCompanyData` call sites and their path-schema inputs;
+  `id` still holds the company id, so the actual HTTP URL is unchanged.
+- **Breaking:** `UserCompanyParameters.type` and `UserCompanyCreateParameters.type` are
+  `'EMPLOYEE' | 'CONTRACTOR'`, without `null`. Omit the value for the create default or to retain it
+  on update. `Users.createCompany()` / `updateCompany()` now reject wrong JSON types before saving:
+  send pay and benefit amounts as decimal strings, minute amounts as integers, and enrollment /
+  overtime flags as booleans. Creating requires a valid `hire_date`; on an administrative update,
+  null or blank `hire_date` still retains the employment start. Custom-field rows require nonblank
+  `custom_field_config_id` and string-or-null `value`; send a list of row objects, not an indexed
+  object. Malformed values return `422` with a field pointer; missing required fields return `400`.
+- **Breaking:** `UserParameters.group_ids` no longer accepts `null`. `Users.createUser()`,
+  `Groups.addUsersToGroup()`, `TimeEntries.createTimeEntry()` / `updateTimeEntry()`,
+  `ComplianceChecks.updateCheck()`, and form-assignment writes require unique nonblank IDs in
+  their group, feature, and assignee arrays. Null, blank, duplicate, or wrong-typed members now
+  return `422` before any write. Omit optional replacement arrays to retain them on update or send
+  `[]` to clear them; `UserGroupParameters.user_ids` must contain at least one ID. Corresponding
+  Zod schemas validate nonblank members and the group-add minimum; uniqueness remains server-side.
+- **Breaking:** `AssetsTransfers.createTransfer()` validates endpoint IDs and `line_items`
+  before moving stock. Supply at most one endpoint per side and at least one side; endpoint IDs
+  must be nonblank strings. Supply a nonempty array of rows with `assets_item_id` and integer
+  `quantity >= 1`; indexed row objects, fractional quantities, numeric strings, and unknown row
+  keys return `422` with pointers. Missing `line_items` or required row fields returns `400`.
+  `AssetsTransferParameters.from_assets_sub_location_id` / `to_assets_sub_location_id` now allow
+  `null` for unbinned stock, matching their generated Zod schemas.
+- **Breaking:** `ApprenticeshipWageSchedules.createWageSchedule()` / `updateWageSchedule()` and
+  `ApprenticeshipWageSchedulePeriods.createPeriod()` / `updatePeriod()` validate JSON types,
+  nullable fields, units, and nonnegative period values before saving. Send `periods_attributes`
+  as an array of row objects. Missing required fields return `400`; malformed or unknown nested
+  fields return `422` with pointers. A period must retain at least one of `min_minutes`,
+  `max_minutes`, or `num_competencies`, including after clearing values. `UpdateWageScheduleErrors`
+  now declares `422: Problem`; `CreatePeriodErrors` now declares `404: Problem` for a missing or
+  inaccessible schedule.
+- **Breaking:** `AssetsAttributes.createAttribute()` / `updateAttribute()`,
+  `Certifications.createCertification()` / `updateCertification()`,
+  `Projects.createProject()` / `updateProject()`, `ComplianceChecks.updateCheck()`, and
+  `Users.updateUser()` reject wrong JSON types and undeclared body fields before saving.
+  Supply nonblank required names, booleans for flags, and only declared keys; nested option-row
+  failures return `422` with a row pointer instead of `400`. The corresponding generated Zod
+  schemas validate nonblank names and IDs. Project date fields require real `YYYY-MM-DD` strings
+  or null; timestamps, loose dates, and empty strings return `422 validation_failed` with a pointer.
+  Send an IANA zone or null for `tz_name` and an integer `0`–`6` or null for `billing_start_day`.
+  `zUserUpdateParameters.birth_date` now validates
+  a `YYYY-MM-DD` calendar date or null; timestamps are not dates.
+- **Breaking:** `Timecodes` writes validate documented flags as booleans and reject blank names,
+  malformed values, and undeclared fields before saving. The create, correction, scheduled-change,
+  and genesis Zod schemas accept temporal strings for server parsing rather than enforcing ISO
+  date-time syntax locally. Omit create's `effective_date` to use now; sending null now returns
+  `422 validation_failed` instead of defaulting. Unparseable strings return `422 invalid_date`.
+  `updateTimecode()`, `scheduleTimecodeChange()`, and `shiftTimecodeGenesis()` validate the body
+  before `If-Match`, so malformed requests can return `400` / `422` ahead of `428`. Preserve the
+  header for valid writes and correct body errors before retrying.
+- **Breaking:** `UserCertifications.approveUserCertification()` requires a company key to name
+  a nonblank `UserCertificationApprovalParameters.approved_by_user_id`; a user key must omit it
+  and approves as itself. A company key's omitted approver is `400`; supplied null or malformed
+  values are `422` with `#/approved_by_user_id`, while a user key naming an approver is `403`.
+  Correct the body for the key type rather than retrying a refused actor.
+- **Breaking:** `People.updateCustomField()` requires a nonempty `custom_fields` array.
+  Missing the list or either row field (`custom_field_config_id` / `value`) now returns
+  `400 parameter_missing`, and extra row keys return `422 validation_failed` with a row-field
+  pointer. Body validation precedes `If-Match`; keep the precondition header for valid batches.
+- **Breaking:** `JobWageDeterminations` and `ProjectWageDeterminations` writes validate
+  subtype fields before saving. Send decimal-string cents, nonblank classifications and trade
+  IDs, and lowercase `construction_category` values. Required create-field omissions now return
+  `400 parameter_missing`; malformed values return `422 validation_failed` with exact pointers.
+  Federal create requests must omit `regional_fields`; even `{}` is refused. On edits,
+  scheduled changes, and genesis shifts, invalid calendar dates (`effective_from` /
+  `effective_date`) now return `validation_failed` instead of `invalid_date`, before `If-Match`
+  failures. Send real `YYYY-MM-DD` dates and handle `Problem.errors` before retrying.
+- **Breaking:** manager and safety-manager user keys no longer receive selectable packages from
+  `PayRateRulePackages.listPayRateRulePackages()`. `getPayRateRulePackage()` and the corresponding
+  `PayRateRules.listPayRateRules()`, `getPayRateRule()`, and `listPayRateRuleHistory()` lookups return
+  `404`. Use an administrator user key for reusable recipe details. Administrator user keys,
+  company keys, and existing reads of hidden determination packages retain their access.
+
+### Removed
+
+- **Breaking:** `TimeEntryParameters` and `zTimeEntryParameters` are removed. Use
+  `TimeEntryCreateParameters` / `zTimeEntryCreateParameters` for creates and
+  `TimeEntryUpdateParameters` / `zTimeEntryUpdateParameters` for edits.
+- **Breaking:** `RegionalWageDeterminationFields` and `zRegionalWageDeterminationFields` are
+  removed. Regional write fields are inline in the owning create, update, or scheduled-change
+  type. Derive a reusable type with
+  `NonNullable<RegionalJobWageDeterminationParameters['regional_fields']>` or its project
+  counterpart. Categorized-fringe fields now allow null in the TypeScript and Zod shape; the
+  server still requires nonnull fringe values for regions that require them and rejects fields
+  the region does not support.
+
+### Fixed
+
+- `TimecodeScheduledChangeParameters.name` is optional. `Timecodes.scheduleTimecodeChange()`
+  can change flags or another attribute without resending the name; only `effective_date` is
+  required. `zTimecodeScheduledChangeParameters` matches this accepted partial write.
+- `ApprenticeshipWageScheduleParameters.periods_attributes` makes `period_number`, `wage_percent`,
+  and `wage_cents` optional in nested rows, including edits or removals of existing periods.
+  Standalone `ApprenticeshipWageSchedulePeriods.createPeriod()` still requires all three.
+  `ApprenticeshipWageScheduleUpdateParameters.periods_attributes` and
+  its Zod schema now use simple row objects, so partial edits need not repeat a progression
+  threshold. The server validates the resulting period rather than just the supplied fields.
+- `ProjectParameters.budget` and `ProjectUpdateParameters.budget` allow null, including through
+  their generated Zod schemas. Send null to clear a budget, a decimal string to set it, or omit
+  it on update to retain it.
+- `FederalJobWageDeterminationParameters` and `FederalProjectWageDeterminationParameters`
+  expose optional nullable `overtime_package_id`. `RegionalJobWageDeterminationParameters` and
+  `RegionalProjectWageDeterminationParameters` expose optional nullable `class_code` and
+  `construction_category`. Corresponding create Zod schemas retain those fields instead of
+  stripping them. Regional `class_code` / `construction_category` remain ignored by the server,
+  and Federal creates still refuse a non-null overtime package; these are schema corrections.
+  Method names and response types are unchanged.
+- `zComplianceCheckParameters.time_due` accepts a string or null instead of requiring ISO
+  date-time syntax. The server parses supplied dates and returns a validation problem for
+  malformed input; consumers using the schema can submit the server's accepted date forms.
+- `AssetsProducts` writes with an out-of-range `default_minimum_quantity` and
+  `ProductionCompletions` writes with an out-of-range `quantity_completed` now return
+  `422 validation_failed` instead of `500 internal_error`. These range problems have no field
+  `errors` array; correct the number rather than retrying a server failure.
+
+See the [API changelog](https://dsptch.app/support/docs/developers/api-changelog#2026-10-13) for the
+complete REST contract details and error behavior.
+
+## [0.35.0] - 2026-10-12
+
+### Added
+
+- `CompetencyCriterionParameters` adds optional nullable `assessment_method` for
+  `CompetenciesCriteria.createCriterion()` / `updateCriterion()`.
+  `CompetencyCriterionResponseObject` adds the required nullable field on reads, writes, and
+  `moveCompetencyCriterion()`. Its union is `'direct_observation' | 'simulation' |
+'oral_questioning' | 'written_questioning' | 'products_of_work' | 'recognized_prior_learning' |
+'witness_testimony' | 'other' | null`; the corresponding Zod schemas include it. Add the key to
+  typed response fixtures. Available to companies with Competencies enabled; the method is a
+  suggestion, and criteria writes still require a draft revision.
+
+### Changed
+
+- **Breaking:** `ProductionCompletionParameters` is one object rather than a union of feature and
+  quantity request types. `ProductionCompletions.createCompletion()` still requires
+  `production_job_scope_price_id` and `performed_by_user_id`; its optional `completable_attributes`
+  exposes both `feature_id` and `quantity_completed`. The job decides which field to send.
+  `zProductionCompletionParameters` now validates this object instead of the ambiguous `oneOf`.
+  Both create and update Zod schemas validate a supplied `quantity_completed` as an integer of at
+  least `1`, and validate nonblank create scope-price and feature ids.
+- **Breaking:** `ProductionCompletions.createCompletion()` rejects null or malformed `work_date`
+  with `422 validation_failed` instead of using today; omit the key for today's date in the job's
+  time zone. Create and update also reject coerced quantities, non-string notes, and malformed
+  `completable_attributes`. Subtype failures now carry a pointer for each refused field in
+  `Problem.errors`; updating `completable_attributes.feature_id` returns `validation_failed` instead
+  of `subtype_foreign_keys`. Correct malformed values rather than retrying them.
+- **Breaking:** `AssetsCategories.createCategory()` / `updateCategory()`,
+  `AssetsItems.createItem()` / `updateItem()` / `createServiceEvent()` / `updateServiceEvent()`, and
+  `AssetsProducts.createProduct()` / `updateProduct()` validate documented JSON types before saving.
+  Supply arrays for `category_attributes`, `attribute_values`, `images_attributes`, and
+  `attachments_attributes`; lone and index-keyed objects now return `422`. Unknown nested row
+  fields return `422` with a field pointer instead of `400`. Attribute values must be string or
+  null, with a nonblank `assets_attribute_id`; missing attribute ids now return `400`, and blank
+  ids `422`. Create without a required item/product name, item product id, service date, or category
+  name now returns `400` rather than model `422`. Corresponding Zod schemas validate nonblank names,
+  attribute ids, and supplied attachment signed ids. The server refuses undeclared keys.
+- **Breaking:** `AssetsItems.updateItem()` refuses serial-only fields on bulk items with
+  `422 subtype_foreign_keys` and a pointer per field instead of succeeding and silently dropping
+  them. Omit `serial_number`, `status`, `purchase_date`, `purchase_price_cents`, `external_id`, and
+  `external_system_url` when updating bulk inventory.
+- **Breaking:** `PayRateRules.shiftPayRateRuleGenesis()` / `schedulePayRateRuleTermination()` return
+  `422 validation_failed` with `#/effective_date` for invalid dates instead of `422 invalid_date`.
+  Missing dates still return `400 parameter_missing`, now with the same pointer. Handle field
+  validation before retrying with `If-Match`; valid requests and method signatures are unchanged.
+- **Breaking:** `PayRateRules.createPayRateRule()`, `updatePayRateRule()`,
+  `schedulePayRateRuleChange()`, `JobWageDeterminationRateRules.createRateRule()`, and
+  `ProjectWageDeterminationRateRules.createProjectWageDeterminationRateRule()` validate recipes
+  before saving. In `PayRatesRuleParameters`, `PayRatesRuleUpdateParameters`,
+  `PayRatesRuleScheduledChangeParameters`, and `RateRuleParameters`, send string `effect.amount_cents`,
+  integer days (`0`–`6`, nonempty), zero-padded `HH:MM` times, integer apprentice periods (`1`–`100`),
+  integer apprentice-hour bounds (`0`–`100000`), and string overtime multipliers (`'1.5' | '2.0'`).
+  Send only fields for the condition's `type`; wrong-kind or unknown nested fields now return
+  `422` with an exact pointer, and missing required recipe fields return `400` instead of model
+  `422`. The corresponding generated Zod schemas validate the new bounds and time pattern.
+  Valid recipe shapes and generated method names are unchanged.
+- **Breaking:** malformed `effective_date` / `effective_from` on those five recipe writes returns
+  `422 validation_failed` with a field pointer instead of `invalid_date`.
+  `PayRateRules.updatePayRateRule()` and `schedulePayRateRuleChange()` validate the body before
+  `If-Match`, so an invalid recipe with no header now returns `400` / `422` instead of `428`.
+  Preserve the existing header for valid writes; omitting recipe halves on edits still retains them.
+
+### Removed
+
+- **Breaking:** `ProductionCompletionBaseParameters`, `ProductionFeatureCompletionParameters`,
+  `ProductionQuantityCompletionParameters`, `zProductionCompletionBaseParameters`,
+  `zProductionFeatureCompletionParameters`, and `zProductionQuantityCompletionParameters` are removed. Use
+  `ProductionCompletionParameters` and `zProductionCompletionParameters` for create payloads.
+- **Breaking:** `AssetsAttachmentParameters` and `zAssetsAttachmentParameters` are removed.
+  Image and attachment rows are inline in their owning request types. Derive a row type from the
+  relevant field, for example
+  `NonNullable<AssetsItemParameters['images_attributes']>[number]`.
+
+### Fixed
+
+- `AssetsCategoryParameters` and `AssetsCategoryUpdateParameters` make each `category_attributes`
+  row's `assets_attribute_id` and `fillable_on` optional, matching accepted requests. Their Zod
+  schemas no longer require these fields; the server still skips a row without an attribute id.
+- `AssetsItemParameters.serial_number` is optional and nullable. Item create/update types and Zod
+  schemas also allow null for `description`, `purchase_date`, `purchase_price_cents`, `external_id`,
+  and `external_system_url`; the update type allows null for `serial_number` as well. Create
+  placement ids (`assets_site_id`, `user_id`, `container_item_id`, `assets_sub_location_id`) are
+  nullable. `zAssetsItemParameters` / `zAssetsItemUpdateParameters` treat `purchase_date` as a nullable
+  string rather than requiring a date-time. These match input the server already accepted.
+
+### Security
+
+- Asset image and service-attachment writes check the upload behind every accepted row. Supply a
+  signed id registered for the owning resource (`assets.items`, `assets.products`, or
+  `assets.items.service_events`); a signed id for another resource or company returns
+  `422 invalid_signed_id`. Index-keyed row objects are now refused under the array contract above.
+
+See the [API changelog](https://dsptch.app/support/docs/developers/api-changelog#2026-10-12) for the
+complete REST contract details.
+
 ## [0.34.0] - 2026-10-09
 
 ### Added