@dsptch-work/api-client 0.41.0 → 0.43.0

package/CHANGELOG.md

@@ -5,6 +5,208 @@ 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.43.0] - 2026-10-22
+
+### Added
+
+- `ProductionPlannedFeatureTasks` adds `listPlannedFeatureTasks()`, `getPlannedFeatureTask()`,
+  `createPlannedFeatureTask()`, `updatePlannedFeatureTask()`, and `updateArchive()`, with
+  `ProductionPlannedFeatureTaskParameters`, `ProductionPlannedFeatureTaskUpdateParameters`,
+  `ProductionPlannedFeatureTaskArchiveParameters`, `ProductionPlannedFeatureTaskResponseObject`,
+  operation types, and Zod schemas. Create requires `feature_id`; the response keeps stable
+  `id` and `task_id` plus nullable `production_completion_id`, `archived_at`, and `time_due`.
+  Intended `task_assignee_user_ids` and deadlines do not record actual crew or completed work.
+  Company keys must supply `performed_by_user_id` on every write, although it is optional in
+  the generated types; user keys may omit it or supply only their own ID. Omission preserves
+  existing metadata on update or re-add; null clears `description` / `time_due`, and `[]`
+  clears intended people. `updateArchive()` requires `body.archived` and
+  `path.planned_feature_task_id`; restoring or re-adding keeps the same identity. List returns
+  both current and archived entries by default; set `query['filter[archived]']` to `false` or
+  `true` to select one state. Grant `jobs.production.job_scope_prices.planned_feature_tasks:read|create|update`
+  and `jobs.production.job_scope_prices.planned_feature_tasks.archives:update` as needed.
+- The new planning Zod input schemas validate `performed_by_user_id` as a UUID, but do not
+  enforce company-key actor requirements, distinct assignees, or valid `tz_name` values;
+  the API validates these. If using these schemas for `time_due`, normalize offset timestamps
+  to UTC `Z`: their `z.iso.datetime()` rejects numeric offsets even though the API accepts them.
+- `ProductionDeliveryTargets` adds `listDeliveryTargets()`, `getDeliveryTarget()`,
+  `createDeliveryTarget()`, `updateDeliveryTarget()`, and `deleteDeliveryTarget()`, with
+  `ProductionDeliveryTargetParameters`, `ProductionDeliveryTargetUpdateParameters`,
+  `ProductionDeliveryTargetResponseObject`, operation types, and Zod schemas. All methods
+  take the owning `path.job_id` / `path.job_scope_price_id`; grant
+  `jobs.production.delivery_targets:read|create|update|delete` as needed. On Feature-tracked
+  jobs, create requires a Job-local calendar `due_date` and
+  `condition_attributes.requirement_kind: 'count' | 'all'`. For `'count'`, supply a positive
+  integer `required_count`; for `'all'`, omit it or send null. Updates preserve omitted fields:
+  switching count to all requires `required_count: null`, and switching all to count requires
+  a positive count. Exported Zod schemas validate dates, enum values, and positive integers,
+  while the API enforces these conditional rules. Company keys are supported; no
+  `performed_by_user_id`, condition identity, or condition type is accepted. Delete returns
+  `204` without a body and removes the target and its condition; planned work and completions remain.
+- `ProductionDeliveryTargetResponseObject.assessment` distinguishes `required_total`,
+  `qualifying_count` (effective work dated on or before the inclusive Job-local deadline),
+  `current_achieved_count` (including later work), and `shortfall`. Handle all five `state`
+  values: `'unavailable'`, `'awaiting_named_scope'`, `'met_by_date'`,
+  `'remaining_before_deadline'`, and `'shortfall_after_deadline'`. Missing visibility of
+  named membership or its completion evidence returns `'unavailable'` with null
+  `qualifying_count`, `current_achieved_count`, and `shortfall`. A fixed count remains visible
+  in `condition.required_count` and `assessment.required_total`; an all requirement's
+  `required_total` is null. Do not treat null as zero or as a missed target; an empty all
+  requirement awaits named scope. List pagination limits
+  targets, while each assessment still uses the whole current named scope. Targets do not
+  create planned work or record completions.
+- `ProductionCompletions` adds `listCompletionHistory()`, `getCompletionHistory()`, and
+  `setCompletionWithdrawal()`, with `ProductionCompletionWithdrawalParameters`, operation types,
+  and Zod schemas. History returns each retained record's current corrected facts, including
+  withdrawn Feature claims, rather than prior versions. It accepts job, scope-kind, Feature,
+  and inclusive `filter[work_date][gte]` / `filter[work_date][lte]` filters. Grant
+  `production.completions.history:read`. Withdrawal uses `path.completion_id` and required
+  `body.withdrawn`; `true` withdraws and `false` restores the same Feature completion ID,
+  idempotently. Grant `production.completions.withdrawals:update`. Quantity completions and
+  restoration over an effective replacement return `422`. The history query Zod schema
+  validates date strings but leaves inverted date ranges to API validation.
+- `Jobs` adds `listCaEcprXmlExports()`, `getCaEcprXmlExport()`, and
+  `createCaEcprXmlExport()`, with `JobCaEcprXmlExportCreateParameters`,
+  `JobCaEcprXmlExportResponseObject`, `JobCaEcprXmlExportsResponseObject`, operation types,
+  and Zod schemas. Grant `jobs.pwa.certified_payrolls.ca_ecpr_xml_exports:read|create` as needed.
+  Create requires a user-scoped key with financial permission and calendar-day `start_date` /
+  `end_date` strings (`YYYY-MM-DD`), with `start_date <= end_date`. It returns `201` with the
+  pending export. Company keys receive `403` on create; missing dates return `400`.
+  A job without matching CA prevailing-wage eligibility returns `422 certified_payroll_format_unavailable`;
+  a window without reportable pay periods returns `422 nothing_exportable`. Inverted windows
+  return `422 validation_failed` pointing to `end_date`; the exported Zod input schema validates
+  individual dates but does not compare their order. Filename is server-owned; the create
+  parameters accept no filename, version, or signing inputs, and creation does not start signing.
+  List is paginated and accepts comma-separated statuses in `query['filter[status]']`. Poll
+  the member read for generation status and a nonnull `file`; `status: 'success'` alone does
+  not guarantee an attached XML or ZIP. Responses include required nullable `invalidated_at`
+  and `invalidation_reason`; this format has no form-version field.
+
+### Changed
+
+- **Required response field:** `ProductionFeatureCompletionResponseObject` and
+  `ProductionQuantityCompletionResponseObject` add `withdrawn_at: string | null` through
+  `ProductionCompletionResponseObject`. Update typed fixtures and mock responses to supply it;
+  the corresponding Zod response schemas now reject omission. Effective Feature completions
+  and all Quantity completions return null. Ordinary completion reads continue to exclude
+  withdrawn Feature claims; use the new history methods to retrieve them.
+- `Jobs.updateJob()` now returns `422` when changing `production_tracking_kind` away from
+  `'feature'` while active planned Feature tasks or delivery targets exist. Archive those tasks
+  and remove the targets first; the existing restriction on recorded completions still applies.
+  `ProductionJobScopePrices.deleteJobScopePrice()` now returns `422` while delivery targets or
+  any planned Feature tasks are retained, including archived tasks. Remove targets before
+  deleting their scope; archiving planned tasks does not enable scope deletion. Generated
+  signatures are unchanged.
+- New WH-347 exports created through `Jobs.createWh347Export()` use a default
+  `JobWh347ExportResponseObject.file.filename` of
+  `wh347_<canonical-job-name>_<first-pay-period-start>_<last-pay-period-end>.zip`.
+  The interval covers the included pay periods; the filename no longer carries the form
+  version. Read `JobWh347ExportResponseObject.version` instead of parsing a filename.
+- The runtime Zod dependency advances from `^4.4.3` to `^4.6.7`.
+
+See the [October 22 API changelog](https://dsptch.app/support/docs/developers/api-changelog#2026-10-22)
+for the complete REST contract details and error behavior.
+
+## [0.42.0] - 2026-10-21
+
+### Added
+
+- `Jobs` adds `listWh347Exports()`, `createWh347Export()`, and `getWh347Export()`, with
+  `JobWh347ExportCreateParameters`, `JobWh347ExportResponseObject`,
+  `JobWh347ExportsResponseObject`, operation types, and Zod schemas. Create requires a
+  user-scoped key and calendar-day `start_date` / `end_date` for a job tracking federal
+  prevailing wage. Grant `jobs.pwa.certified_payrolls.wh347_exports:read|create`. Poll the
+  member read for generation status and a nonnull `file`; `status: 'success'` alone does not
+  guarantee an attached file. API creation does not start signing.
+- `AssetsItems.deleteFormAssignmentTask()`, `Jobs.deleteJobFormAssignmentTask()`,
+  `OversiteFeatureFormAssignmentTasks.deleteFeatureFormAssignmentTask()`, and
+  `OversiteSiteFormAssignmentTasks.deleteSiteFormAssignmentTask()` add operation types and
+  Zod schemas. Supply the nested task's ID and the corresponding delete scope. Only the open,
+  incomplete permanent copy can be ended; success returns `204`, and an ineligible copy
+  returns `422 not_incomplete_permanent_copy`. Recurrence changes stay on update.
+- `TimeEntryCreateParameters` and `TimeEntryUpdateParameters` accept optional nullable
+  `one_five_x_adder_rate_cents` and `two_x_adder_rate_cents` through `TimeEntries.createTimeEntry()`
+  and `updateTimeEntry()`. Each premium is added after applying that tier's overtime multiplier
+  to the base hourly rate: $30 × 1.5 + $3 pays $48 per hour. Send nonnegative decimal cents
+  strings, including fractional cents or zero. Omission derives
+  the automatic premium on create and preserves it on update; null resets that tier to automatic.
+  `TimeEntryResponseObject` adds the optional nullable amounts and read-only
+  `one_five_x_adder_rate_src_type` / `two_x_adder_rate_src_type`, each
+  `'position' | 'prevailing_wage' | 'custom' | null`. Company keys and company-admin user keys
+  can write and receive these fields; other user keys receive `403` when writing them,
+  including null. The Zod input schemas validate decimal strings.
+
+### Changed
+
+- **Breaking:** `Billing.listPwaUserCountsByProjectByMonths()` now returns
+  `ListPwaUserCountsByProjectByMonthsResponse` as `{ meta, links, data }` instead of a bare
+  array. Read rows from `data` and follow pagination; the default page has 20 rows and
+  `query['page[limit]']` is capped at 100. `query['filter[year_month]']` must be `YYYY-MM`;
+  the generated Zod query schema now validates this format and positive integer limits.
+- **Breaking response change:** `ProductionJobScopePriceResponseObject.unit_price_cents`
+  becomes optional nullable. Handle null as unknown and any decimal string numerically equal
+  to zero (for example, `"0.0"`) as a known zero, separately from omission for financial access.
+  `ProductionJobScopePriceParameters.unit_price_cents`
+  becomes optional nullable, and `ProductionJobScopePriceUpdateParameters.unit_price_cents`
+  becomes nullable. `ProductionJobScopePrices.createJobScopePrice()` accepts omission or null;
+  `updateJobScopePrice()` preserves omission and clears to unknown on null. The matching
+  Zod schemas accept these shapes.
+- `ProductionCompletions.deleteCompletion()` now withdraws Feature completions while retaining
+  their ID and crew history; repeated deletes return `200`. Withdrawn reports disappear from
+  `listCompletions()` and `getCompletion()` returns `404`; updating one does not restore it.
+  Quantity-completion deletion and generated signatures are unchanged.
+
+### Removed
+
+- **Breaking:** `RegionalWageDeterminationFieldsResponse`, returned in job and project
+  determination `regional_fields`, no longer includes `one_five_x_adder_rate_cents`,
+  `two_x_adder_rate_cents`, `one_five_x_fringe_adder_rate_cents`, or
+  `two_x_fringe_adder_rate_cents`. Read overtime wage and fringe premiums through
+  `JobWageDeterminationRateRules` or `ProjectWageDeterminationRateRules`. Its generated
+  dictionary type and Zod validator are unchanged, so they do not expose this removal;
+  categorized fringe fields remain available where the region requires them.
+
+### Fixed
+
+- **Breaking runtime validation:** `Jobs.createGoodFaithEffortException()` and
+  `updateGoodFaithEffortException()` require `minutes_per_apprentice` to be a positive
+  integer multiple of 60, such as `480` for eight hours. The parameter types remain `number | null`,
+  and the generated Zod schemas do not enforce the multiple-of-60 rule; the API returns `422`
+  for other values.
+- `Certifications.createCertification()` and `UserRoles.addUserRoles()` now return `201`.
+  `CreateCertificationResponses` and `AddUserRolesResponses` replace their `200` keys with
+  `201`; code inspecting status codes or those keyed types must change.
+- `Jobs.createPosition()` / `updatePosition()` reject a position with only one schedule bound
+  with `422` and a field pointer, rather than silently leaving an unscheduled position unchanged.
+  Send both bounds to schedule an unscheduled position; existing request types are unchanged.
+- Repeated members now return `422` in `CompetenciesCriteria.createCriterion()` /
+  `updateCriterion()` assessment methods, `AssetsProducts.seedServiceScheduleTemplate()` item IDs,
+  `syncServiceScheduleTemplate()` schedule IDs, and the four worker-demographic code arrays in
+  `Users.createCompanyUserDetail()`, `updateCompanyUserDetail()`, and
+  `createUser()`'s `company_user_pwa_info`. Deduplicate lists before submitting them; generated
+  array types and Zod validators are unchanged.
+- `ProjectSites.listProjectSites()`, `ProjectWageDeterminations.listProjectWageDeterminations()`,
+  `ProjectWageDeterminationRateRules.listProjectWageDeterminationRateRules()`,
+  `ProjectDocuments.listProjectDocumentVersions()`, and `AssetsItems.listVersions()` now reject
+  `filter[...]` keys with `400`. Remove unsupported filters even though generated query types
+  expose hidden malformed-filter test parameters; these lists support no filters.
+
+### Security
+
+- **Breaking runtime authorization:** `TimeCardResponseObject` and
+  `JobTimeCardDayResponseObject` now omit `pay_cents`, `base_wage_pay_cents`,
+  `one_five_x_adder_cents`, and `two_x_adder_cents` for non-admin user keys reading another
+  person's card, including managers. Day responses also omit the corresponding `cumulative_`
+  and `weekly_cumulative_` fields. Company keys, company admins, and the card's owner retain
+  wages; per diem rates are unchanged. These properties were already optional in the generated
+  types and Zod schemas; handle their absence on both list and member reads.
+- **Breaking runtime authorization:** `PerDiems.listPerDiems()` now returns `403` for user keys
+  whose user is neither an admin nor a manager at the key's company. `getPerDiem()` now admits
+  managers; company-key access is unchanged and user-key writes remain admin-only. Signatures
+  are unchanged.
+
+See the [October 21 API changelog](https://dsptch.app/support/docs/developers/api-changelog#2026-10-21)
+for the complete REST contract details and error behavior.
+
 ## [0.41.0] - 2026-10-20
 
 ### Added