clockster 0.3.0__tar.gz → 0.4.0__tar.gz

{clockster-0.3.0 → clockster-0.4.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.0
+
+### May break your build (types only)
+
+Nothing. Three operations and one set are new.
+
+### Changed in the API
+
+Reaches you whether or not you update this package.
+
+- `GET /payroll/payslips` answers the `external_id` of a dismissed employee. It was `None` on their
+  payslips.
+
+### New
+
+- `clockster.payroll.single_adjustments`: `list`, `create` and `delete`, blocking and awaited, over
+  `/payroll/single-adjustments` — one-off additions and deductions that the next calculation of a
+  payslip takes in. `create` files up to 100 at a time, all or nothing; pass `idempotency_key=` so a
+  retry does not file them twice.
+- `PayrollSingleAdjustmentsType` in `clockster.models`, a `Literal` of the six types, for `type` on
+  `create` and the `types` filter.
+
 ## 0.3.0
 
 ### May break your build (types only)

{clockster-0.3.0 → clockster-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clockster
-Version: 0.3.0
+Version: 0.4.0
 Summary: Official Python SDK for the Clockster Company API
 Project-URL: Homepage, https://github.com/clockster/sdk-python#readme
 Project-URL: Source, https://github.com/clockster/sdk-python
@@ -126,6 +126,7 @@ everything.
 | `documents` | `list` `get` `upsert` `delete` |
 | `files` | `upload` |
 | `payroll.payslips` | `list` |
+| `payroll.single_adjustments` | `list` `create` `delete` |
 | `user_requests` | `list` `get` |
 | `webhooks` | `list` `get` `create` `update` `delete` `rotate_secret` |
 | `webhooks.deliveries` | `list` `get` `redeliver` |

{clockster-0.3.0 → clockster-0.4.0}/README.md

@@ -97,6 +97,7 @@ everything.
 | `documents` | `list` `get` `upsert` `delete` |
 | `files` | `upload` |
 | `payroll.payslips` | `list` |
+| `payroll.single_adjustments` | `list` `create` `delete` |
 | `user_requests` | `list` `get` |
 | `webhooks` | `list` `get` `create` `update` `delete` `rotate_secret` |
 | `webhooks.deliveries` | `list` `get` `redeliver` |

{clockster-0.3.0 → clockster-0.4.0}/openapi/company-v3.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Clockster Company API",
     "version": "3.0.0",
-    "description": "A server-to-server API for reading and writing your company's employees, structure,\nschedules, attendance, tasks and documents. It is what an HR system, a payroll system or a\nturnstile of your own talks to.\n\nOne token authenticates a company. There is no per-user identity here, so everything a call\ncan see and change belongs to the company holding the token, and another company's id\nanswers `404` rather than `403` — you cannot learn that it exists.\n\n## Quickstart\n\nA first integration usually goes in this order, because each step needs the one before it.\n\n**1. Confirm the key.** `GET /me` answers the company it belongs to and changes nothing.\n\n**2. Write the structure.** `POST /locations/upsert`, then `/departments/upsert` and\n`/positions/upsert` if you use them. Send each row with the `external_id` your own system\nknows it by. Read the ids back out of the answer — an employee is filed against a location\nby id.\n\n**3. Write the roster.** `POST /users/upsert`, up to 100 people a call. `first_name`, `role`\nand `location_id` are the minimum; send `external_id` on every person so the next sync\nupdates rather than duplicates.\n\n**4. Say who works when.** `POST /schedules` takes a list, each item a kind of day, the\ndates it falls on and the people it is for.\n\n**5. Read what happened.** `GET /timesheets?date_from=…&date_to=…` answers one row per\nperson per day: what was planned, and with `include=actual,variance` what was recorded and\nhow the two differ. `GET /attendance` answers the raw clock-ins instead.\n\n**6. Stop polling.** Create a webhook endpoint and subscribe to the events you care about;\nre-read on the event rather than on a timer.\n\nFrom then on a sync is `updated_since` plus the cursor: ask for what changed, page through\nit, remember the instant you asked at.\n\n## SDK\n\n| Language | Package | Install |\n| --- | --- | --- |\n| TypeScript, Node | [`@clockster/sdk`](https://www.npmjs.com/package/@clockster/sdk) | `npm install @clockster/sdk` |\n| Python | [`clockster`](https://pypi.org/project/clockster/) | `pip install clockster` |\n| Go | [`github.com/clockster/sdk-go`](https://pkg.go.dev/github.com/clockster/sdk-go) | `go get github.com/clockster/sdk-go` |\n| PHP | [`clockster/sdk`](https://packagist.org/packages/clockster/sdk) | `composer require clockster/sdk` |\n\nAll four are typed from this document and generated from it, so an operation is called the\nsame thing in each. Sources and issues:\n[sdk-typescript](https://github.com/clockster/sdk-typescript),\n[sdk-python](https://github.com/clockster/sdk-python),\n[sdk-go](https://github.com/clockster/sdk-go),\n[sdk-php](https://github.com/clockster/sdk-php).\n\nNone of them carries a dependency worth the name: TypeScript and Go have none at all,\nPython has `httpx`, PHP has curl. Each answers what its own language reads most plainly —\nobjects, dictionaries described by `TypedDict`s, structs, arrays described by array shapes\n— and each walks a cursor-paged listing the way that language walks anything. The Python\nclient mirrors every operation both blocking and awaited.\n\n**Your language is not on the list.** This document is public and machine-readable, so a\nclient for any language is one command away, and it will be as complete as the list above —\nthe published package is generated from this same file.\n\n```\nnpx @hey-api/openapi-ts -i https://api.clockster.com/openapi/v3.json -o ./clockster\n```\n\nOther generators read it as well; `openapi-generator` is the usual one outside JavaScript.\n\n**Worked examples** live beside each package, in its `examples` directory: a roster sync\nin, a timesheet export out. Google Sheets is there too, beside the\n[TypeScript one](https://github.com/clockster/sdk-typescript/tree/main/examples) — a\nspreadsheet that fills itself from your roster and timesheets, and does not use the package\nat all, since Apps Script has no npm, so it is this API over `UrlFetchApp`.\n\n**Versions.** Each SDK follows its own semver, unrelated to the version of this API and to\nthe others'. A new API version is a major release of a package rather than a second package.\n\n## Making a request\n\nEvery path below is appended to:\n\n```\nhttps://api.clockster.com/company/v3/\n```\n\nThe key is issued in the web application, under the API section, and goes on every request\nas a bearer credential:\n\n```\nAuthorization: Bearer {ACCESS-TOKEN}\n```\n\nA missing, deleted or expired key answers `401` from that request onward. Issue a new one\nin the same place; there is no call here that mints one.\n\nBodies are JSON, and `Content-Type: application/json` is required on any request that\ncarries one. The single exception is `POST /files`, which takes `multipart/form-data`\nbecause it carries bytes. Responses are JSON throughout.\n\n## Pagination\n\nListings page on a cursor rather than a page number. Read `meta.next_cursor` and send it\nback as `cursor`; a null one means you have reached the end. `per_page` sets the size, up\nto 100.\n\nA cursor encodes a position in a fixed ordering, so nothing is repeated or skipped while\nthe data is being written to underneath you — which a page number cannot promise. One\nissued under a different ordering is refused rather than silently restarting the list, and\nthe refusal names the ordering that was expected.\n\nChanging the filters mid-walk is not refused and not meaningful: start again from the\nfirst page when you change them.\n\nThere is no total count. Ask for the next page until there is no cursor.\n\n## Filtering\n\nFilters that take a list match any of the values in it, and separate filters all have to\nhold: `?locations=1,2&positions=7` means \"at location 1 or 2, and holding position 7\".\nRepeating the parameter (`locations[]=1&locations[]=2`) means the same thing.\n\nEvery list has a cap, stated on the parameter — 100 ids on most of them. A filter only\never narrows within your own company, so it cannot be used to find out what another one\nholds.\n\n**`updated_since` is how a sync stays cheap.** It takes an instant and answers only rows\nchanged at or after it. Keep the time you asked at, not the time you finished, and overlap\nby a minute on the next call.\n\nThere is no sort parameter: each listing has one fixed ordering, oldest first — by `id`,\nor by the moment of the mark on `GET /attendance`.\n\nOldest first is what lets one walk finish the job: rows written while you are paging are\nappended ahead of the cursor and come back in the same pass. It also means a first call\nlands on the oldest row there is, which on a long-lived company is years back. When you\nwant recent activity rather than all of it, that is what `updated_since` is for.\n\n## Choosing what comes back\n\nA response carries its own fields always. Related objects are loaded only when `include`\nnames them, comma-separated: `?include=location,department`. What each endpoint accepts is\nlisted on that endpoint, and a name it does not accept is refused rather than ignored.\n\n**A key that was not asked for is absent, never null.** `null` means the value is known to\nbe empty; an absent key means you did not ask. Code that treats the two the same will\neventually record somebody's department as having been cleared.\n\n## Writing\n\nEvery write takes a list, and most are keyed on ids you own: send items carrying an\n`external_id` — a key from your own system that we never generate — and each one creates or\nupdates depending on whether that key is already known here. The answer says which happened,\nper item, in the order sent. Up to 100 items a call.\n\n**A batch is all or nothing.** One unacceptable item refuses the whole request before\nanything is written, so a `422` means none of it landed and you are never left guessing\nwhich half applied.\n\n**A resend of a keyed write is safe** and is the intended way to recover from a timeout or\na failure of any kind: whatever landed the first time matches its key and is updated rather\nthan duplicated.\n\n**An omitted field keeps its stored value.** Send a field as `null` to clear it.\n\nTwo writes carry no key of your own. `POST /attendance` takes up to 100 marks and drops one\nit already holds, so a resend cannot double somebody's day. `POST /schedules` takes 25 and\nhas nothing to match on — read its answer rather than sending it again blind.\n\n## Rate limits\n\n100 requests a minute, counted against the token and shared by every process using it. Each\nversion of this API has a budget of its own, so reading one does not spend the other's.\nOver the limit answers `429` until the window rolls over.\n\n| Header | Sent on | Meaning |\n| --- | --- | --- |\n| `X-RateLimit-Limit` | every response | Requests allowed in the window. |\n| `X-RateLimit-Remaining` | every response | Requests left. Slow down as it nears zero rather than waiting for the refusal. |\n| `Retry-After` | `429` | Seconds to wait before trying again. |\n| `X-RateLimit-Reset` | `429` | Unix timestamp at which the window rolls over. |\n\n## Retries and failures\n\n**Retry a `429` and a `5xx`; do not retry a `4xx`.** A refusal we cannot fix by being asked\nagain is a refusal — retrying it burns your rate limit and changes nothing. On a `429`,\n`Retry-After` says how long to wait.\n\nBack off between attempts rather than retrying immediately, and give up after a handful.\n\n**A request that times out with no answer is unknown, not failed** — it may have been\napplied. Send it again: a keyed batch converges on what you meant rather than doubling\nanything, and `POST /attendance` drops a mark it already holds for the same person, moment\nand direction.\n\n**Where there is no such key, send an `Idempotency-Key`.** Four writes create something with\nnothing to match a second attempt against — a rota, a webhook endpoint, a rotated secret, a\ndelivery sent again. Choose a value per attempt, send it in that header, and a retry carrying\nthe same one is answered with the first result rather than performed again. The answer to a\nreplay says so with `Idempotency-Replayed: true`.\n\nA key is remembered for 24 hours and belongs to the request it was first used for: sending it\nwith a different body answers `409` and `idempotency_key_reused` rather than handing you\nsomebody else's result. While the first request is still running, a second carrying the same\nkey answers `409` and `idempotency_key_in_flight` — wait rather than retry. A refusal is not\nremembered, so a key may be reused once its body is fixed.\n\nThe header is optional, and unnecessary on everything keyed on an `external_id`.\n\n## Dates and times\n\nInstants are ISO 8601 with an offset, and that is how they are answered:\n`2026-03-02T09:00:00+05:00`. Where you write one — the `datetime` of a clock-in — the\noffset is required, because the mark's own zone is read off it.\n\nPlain dates are `YYYY-MM-DD` and carry no time or zone: a date of birth, a contract's\nexpiry, the day a shift falls on. The day somebody worked means the same thing to them\nwherever the reader is.\n\nClock times are `HH:MM:SS`, read in the timezone stated beside them. A shift that starts at\n09:00 starts at 09:00 locally, whatever the offset is that week.\n\nDurations are seconds.\n\n## Numbers\n\nMoney and other decimal amounts are answered as JSON numbers rounded to two places. JSON\nnumbers carry no scale, so a whole amount arrives as `1500` rather than `1500.00` — it is\nthe same number. Do not accumulate them in binary floating point.\n\nIds are integers. Anything that looks like a number but is a label — an employee code, a\nnational id — is a string, and a leading zero in it is part of the value.\n\nField names are `snake_case` throughout, in both directions.\n\n## Keeping the key safe\n\nThe token grants everything on this API for the whole company: the roster, attendance,\npayslips, documents. Treat it as you would a password.\n\n**It belongs on a server you control.** Do not ship it in a mobile app, a browser page or\nanything else a user can read, and do not commit it.\n\n**A company has one key, and replacing it is immediate.** Issuing a new one in the web\napplication revokes the old one at once — there is no window where both answer, so a\nreplacement is a cutover rather than a migration. Plan it for a moment when a failed call\ncosts nothing, and expect the next request on the old key to answer `401`.\n\nThat also means several systems sharing a company's key stand or fall together: replacing it\nfor one cuts off the rest, and nothing in the request log tells which of them made a call.\n\n## Compatibility\n\nThe document at `https://api.clockster.com/openapi/v3.json` is this API's contract, built\nfrom the deployment that answers it. Point a client generator at it rather than writing one\nby hand.\n\n**New fields may be added to any response at any time, and are not a breaking change.**\nIgnore keys you do not recognise; do not fail on them. New optional parameters and new\nendpoints arrive the same way.\n\nAn `operationId` never changes once published, and neither does the meaning of an existing\nfield. A change that would break a caller gets a new version of the whole surface, side by\nside with this one, rather than being applied underneath you. V2 remains available and is\ndocumented beside this.\n\n## Getting help\n\nWrite to `info@clockster.com` with what you called, what you expected and what came back.\nInclude the `error.request_id` from the response — every refusal carries one, and it is how\nwe find the request in our logs.\n\nRequests made with your key are also readable in the web application, under the API\nsection: the path, the status and the body that was sent."
+    "description": "A server-to-server API for reading and writing your company's employees, structure,\nschedules, attendance, tasks and documents. It is what an HR system, a payroll system or a\nturnstile of your own talks to.\n\nOne token authenticates a company. There is no per-user identity here, so everything a call\ncan see and change belongs to the company holding the token, and another company's id\nanswers `404` rather than `403` — you cannot learn that it exists.\n\n## Quickstart\n\nA first integration usually goes in this order, because each step needs the one before it.\n\n**1. Confirm the key.** `GET /me` answers the company it belongs to and changes nothing.\n\n**2. Write the structure.** `POST /locations/upsert`, then `/departments/upsert` and\n`/positions/upsert` if you use them. Send each row with the `external_id` your own system\nknows it by. Read the ids back out of the answer — an employee is filed against a location\nby id.\n\n**3. Write the roster.** `POST /users/upsert`, up to 100 people a call. `first_name`, `role`\nand `location_id` are the minimum; send `external_id` on every person so the next sync\nupdates rather than duplicates.\n\n**4. Say who works when.** `POST /schedules` takes a list, each item a kind of day, the\ndates it falls on and the people it is for.\n\n**5. Read what happened.** `GET /timesheets?date_from=…&date_to=…` answers one row per\nperson per day: what was planned, and with `include=actual,variance` what was recorded and\nhow the two differ. `GET /attendance` answers the raw clock-ins instead.\n\n**6. Stop polling.** Create a webhook endpoint and subscribe to the events you care about;\nre-read on the event rather than on a timer.\n\nFrom then on a sync is `updated_since` plus the cursor: ask for what changed, page through\nit, remember the instant you asked at.\n\n## SDK\n\n| Language | Package | Install |\n| --- | --- | --- |\n| TypeScript, Node | [`@clockster/sdk`](https://www.npmjs.com/package/@clockster/sdk) | `npm install @clockster/sdk` |\n| Python | [`clockster`](https://pypi.org/project/clockster/) | `pip install clockster` |\n| Go | [`github.com/clockster/sdk-go`](https://pkg.go.dev/github.com/clockster/sdk-go) | `go get github.com/clockster/sdk-go` |\n| PHP | [`clockster/sdk`](https://packagist.org/packages/clockster/sdk) | `composer require clockster/sdk` |\n\nAll four are typed from this document and generated from it, so an operation is called the\nsame thing in each. Sources and issues:\n[sdk-typescript](https://github.com/clockster/sdk-typescript),\n[sdk-python](https://github.com/clockster/sdk-python),\n[sdk-go](https://github.com/clockster/sdk-go),\n[sdk-php](https://github.com/clockster/sdk-php).\n\nNone of them carries a dependency worth the name: TypeScript and Go have none at all,\nPython has `httpx`, PHP has curl. Each answers what its own language reads most plainly —\nobjects, dictionaries described by `TypedDict`s, structs, arrays described by array shapes\n— and each walks a cursor-paged listing the way that language walks anything. The Python\nclient mirrors every operation both blocking and awaited.\n\n**Your language is not on the list.** This document is public and machine-readable, so a\nclient for any language is one command away, and it will be as complete as the list above —\nthe published package is generated from this same file.\n\n```\nnpx @hey-api/openapi-ts -i https://api.clockster.com/openapi/v3.json -o ./clockster\n```\n\nOther generators read it as well; `openapi-generator` is the usual one outside JavaScript.\n\n**Worked examples** live beside each package, in its `examples` directory: a roster sync\nin, a timesheet export out. Google Sheets is there too, beside the\n[TypeScript one](https://github.com/clockster/sdk-typescript/tree/main/examples) — a\nspreadsheet that fills itself from your roster and timesheets, and does not use the package\nat all, since Apps Script has no npm, so it is this API over `UrlFetchApp`.\n\n**Versions.** Each SDK follows its own semver, unrelated to the version of this API and to\nthe others'. A new API version is a major release of a package rather than a second package.\n\n## Making a request\n\nEvery path below is appended to:\n\n```\nhttps://api.clockster.com/company/v3/\n```\n\nThe key is issued in the web application, under the API section, and goes on every request\nas a bearer credential:\n\n```\nAuthorization: Bearer {ACCESS-TOKEN}\n```\n\nA missing, deleted or expired key answers `401` from that request onward. Issue a new one\nin the same place; there is no call here that mints one.\n\nBodies are JSON, and `Content-Type: application/json` is required on any request that\ncarries one. The single exception is `POST /files`, which takes `multipart/form-data`\nbecause it carries bytes. Responses are JSON throughout.\n\n## Pagination\n\nListings page on a cursor rather than a page number. Read `meta.next_cursor` and send it\nback as `cursor`; a null one means you have reached the end. `per_page` sets the size, up\nto 100.\n\nA cursor encodes a position in a fixed ordering, so nothing is repeated or skipped while\nthe data is being written to underneath you — which a page number cannot promise. One\nissued under a different ordering is refused rather than silently restarting the list, and\nthe refusal names the ordering that was expected.\n\nChanging the filters mid-walk is not refused and not meaningful: start again from the\nfirst page when you change them.\n\nThere is no total count. Ask for the next page until there is no cursor.\n\n## Filtering\n\nFilters that take a list match any of the values in it, and separate filters all have to\nhold: `?locations=1,2&positions=7` means \"at location 1 or 2, and holding position 7\".\nRepeating the parameter (`locations[]=1&locations[]=2`) means the same thing.\n\nEvery list has a cap, stated on the parameter — 100 ids on most of them. A filter only\never narrows within your own company, so it cannot be used to find out what another one\nholds.\n\n**`updated_since` is how a sync stays cheap.** It takes an instant and answers only rows\nchanged at or after it. Keep the time you asked at, not the time you finished, and overlap\nby a minute on the next call.\n\nThere is no sort parameter: each listing has one fixed ordering, oldest first — by `id`,\nor by the moment of the mark on `GET /attendance`.\n\nOldest first is what lets one walk finish the job: rows written while you are paging are\nappended ahead of the cursor and come back in the same pass. It also means a first call\nlands on the oldest row there is, which on a long-lived company is years back. When you\nwant recent activity rather than all of it, that is what `updated_since` is for.\n\n## Choosing what comes back\n\nA response carries its own fields always. Related objects are loaded only when `include`\nnames them, comma-separated: `?include=location,department`. What each endpoint accepts is\nlisted on that endpoint, and a name it does not accept is refused rather than ignored.\n\n**A key that was not asked for is absent, never null.** `null` means the value is known to\nbe empty; an absent key means you did not ask. Code that treats the two the same will\neventually record somebody's department as having been cleared.\n\n## Writing\n\nEvery write takes a list, and most are keyed on ids you own: send items carrying an\n`external_id` — a key from your own system that we never generate — and each one creates or\nupdates depending on whether that key is already known here. The answer says which happened,\nper item, in the order sent. Up to 100 items a call.\n\n**A batch is all or nothing.** One unacceptable item refuses the whole request before\nanything is written, so a `422` means none of it landed and you are never left guessing\nwhich half applied.\n\n**A resend of a keyed write is safe** and is the intended way to recover from a timeout or\na failure of any kind: whatever landed the first time matches its key and is updated rather\nthan duplicated.\n\n**An omitted field keeps its stored value.** Send a field as `null` to clear it.\n\nThree writes carry no key of your own. `POST /attendance` takes up to 100 marks and drops one\nit already holds, so a resend cannot double somebody's day. `POST /schedules` takes 25 and\n`POST /payroll/single-adjustments` 100, and neither has anything to match on — read the\nanswer rather than sending it again blind.\n\n## Rate limits\n\n100 requests a minute, counted against the token and shared by every process using it. Each\nversion of this API has a budget of its own, so reading one does not spend the other's.\nOver the limit answers `429` until the window rolls over.\n\n| Header | Sent on | Meaning |\n| --- | --- | --- |\n| `X-RateLimit-Limit` | every response | Requests allowed in the window. |\n| `X-RateLimit-Remaining` | every response | Requests left. Slow down as it nears zero rather than waiting for the refusal. |\n| `Retry-After` | `429` | Seconds to wait before trying again. |\n| `X-RateLimit-Reset` | `429` | Unix timestamp at which the window rolls over. |\n\n## Retries and failures\n\n**Retry a `429` and a `5xx`; do not retry a `4xx`.** A refusal we cannot fix by being asked\nagain is a refusal — retrying it burns your rate limit and changes nothing. On a `429`,\n`Retry-After` says how long to wait.\n\nBack off between attempts rather than retrying immediately, and give up after a handful.\n\n**A request that times out with no answer is unknown, not failed** — it may have been\napplied. Send it again: a keyed batch converges on what you meant rather than doubling\nanything, and `POST /attendance` drops a mark it already holds for the same person, moment\nand direction.\n\n**Where there is no such key, send an `Idempotency-Key`.** Five writes create something with\nnothing to match a second attempt against — a rota, a one-off payroll adjustment, a webhook\nendpoint, a rotated secret, a delivery sent again. Choose a value per attempt, send it in\nthat header, and a retry carrying the same one is answered with the first result rather than\nperformed again. The answer to a replay says so with `Idempotency-Replayed: true`.\n\nA key is remembered for 24 hours and belongs to the request it was first used for: sending it\nwith a different body answers `409` and `idempotency_key_reused` rather than handing you\nsomebody else's result. While the first request is still running, a second carrying the same\nkey answers `409` and `idempotency_key_in_flight` — wait rather than retry. A refusal is not\nremembered, so a key may be reused once its body is fixed.\n\nThe header is optional, and unnecessary on everything keyed on an `external_id`.\n\n## Dates and times\n\nInstants are ISO 8601 with an offset, and that is how they are answered:\n`2026-03-02T09:00:00+05:00`. Where you write one — the `datetime` of a clock-in — the\noffset is required, because the mark's own zone is read off it.\n\nPlain dates are `YYYY-MM-DD` and carry no time or zone: a date of birth, a contract's\nexpiry, the day a shift falls on. The day somebody worked means the same thing to them\nwherever the reader is.\n\nClock times are `HH:MM:SS`, read in the timezone stated beside them. A shift that starts at\n09:00 starts at 09:00 locally, whatever the offset is that week.\n\nDurations are seconds.\n\n## Numbers\n\nMoney and other decimal amounts are answered as JSON numbers rounded to two places. JSON\nnumbers carry no scale, so a whole amount arrives as `1500` rather than `1500.00` — it is\nthe same number. Do not accumulate them in binary floating point.\n\nIds are integers. Anything that looks like a number but is a label — an employee code, a\nnational id — is a string, and a leading zero in it is part of the value.\n\nField names are `snake_case` throughout, in both directions.\n\n## Keeping the key safe\n\nThe token grants everything on this API for the whole company: the roster, attendance,\npayslips, documents. Treat it as you would a password.\n\n**It belongs on a server you control.** Do not ship it in a mobile app, a browser page or\nanything else a user can read, and do not commit it.\n\n**A company has one key, and replacing it is immediate.** Issuing a new one in the web\napplication revokes the old one at once — there is no window where both answer, so a\nreplacement is a cutover rather than a migration. Plan it for a moment when a failed call\ncosts nothing, and expect the next request on the old key to answer `401`.\n\nThat also means several systems sharing a company's key stand or fall together: replacing it\nfor one cuts off the rest, and nothing in the request log tells which of them made a call.\n\n## Compatibility\n\nThe document at `https://api.clockster.com/openapi/v3.json` is this API's contract, built\nfrom the deployment that answers it. Point a client generator at it rather than writing one\nby hand.\n\n**New fields may be added to any response at any time, and are not a breaking change.**\nIgnore keys you do not recognise; do not fail on them. New optional parameters and new\nendpoints arrive the same way.\n\nAn `operationId` never changes once published, and neither does the meaning of an existing\nfield. A change that would break a caller gets a new version of the whole surface, side by\nside with this one, rather than being applied underneath you. V2 remains available and is\ndocumented beside this.\n\n## Getting help\n\nWrite to `info@clockster.com` with what you called, what you expected and what came back.\nInclude the `error.request_id` from the response — every refusal carries one, and it is how\nwe find the request in our logs.\n\nRequests made with your key are also readable in the web application, under the API\nsection: the path, the status and the body that was sent."
   },
   "servers": [
     {
@@ -71,7 +71,7 @@
     },
     {
       "name": "Payroll",
-      "description": "Payslips as calculated, for the months they were calculated for."
+      "description": "Payslips as calculated, for the months they were calculated for, and the one-off additions and deductions that go into the next calculation."
     },
     {
       "name": "Webhooks",
@@ -5569,6 +5569,747 @@
         "description": "Reading only. Nothing on this surface creates or changes a payslip.\n\n**Amounts carry their currency.** A payslip that carries none — one built from a salary\nfiled before the field was required — answers the company's own currency rather than\nnull, so you do not have to invent that fallback yourself.\n\n**The line items are here**: `additions`, `deductions` and `allowances`, each with its\n`title`, `value` and `pre_tax`, which is what decides whether an amount lands before tax\nis worked out.\n\n**`loan_repaid` is what was taken back against an advance.** An advance is not a\ndeduction: it becomes a loan and is repaid on scheduled days, so it never appears in\n`deductions` and a caller subtracting the line items from the total will be out by\nexactly this amount. The figure folds together loan repayments and one-off loan\nadjustments, because that is how the calculation records them.\n\n**The parts do not add up to `take_home`, and are not meant to.** Taxes and the gross\nfigure are not published here, so what you get is what was added, taken off and repaid —\nnot a derivation of the total.\n\n**`updated_since` matters more here than anywhere**: a payslip is recalculated and moves\nfrom `draft` to `approved` to `paid`, so without it a caller re-reads every month\nforever. `months` is `YYYY-MM`, and takes a list, so a quarter is one request."
       }
     },
+    "/company/v3/payroll/single-adjustments": {
+      "get": {
+        "operationId": "company.v3.payroll.single-adjustments.index",
+        "tags": [
+          "Payroll"
+        ],
+        "summary": "List single adjustments",
+        "parameters": [
+          {
+            "name": "per_page",
+            "in": "query",
+            "required": false,
+            "description": "How many rows one page holds. Defaults to 50.",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 50
+            }
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "required": false,
+            "description": "The `meta.next_cursor` of the previous page. Omit it for the first. A cursor is bound to the filters it was issued under — change them and start again.",
+            "schema": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "maxLength": 512
+            }
+          },
+          {
+            "name": "users",
+            "in": "query",
+            "required": false,
+            "description": "Only rows belonging to these people, by id.",
+            "style": "form",
+            "explode": false,
+            "schema": {
+              "type": [
+                "array",
+                "null"
+              ],
+              "maxItems": 100,
+              "items": {
+                "type": "integer"
+              }
+            }
+          },
+          {
+            "name": "types",
+            "in": "query",
+            "required": false,
+            "description": "Only rows of these types.",
+            "style": "form",
+            "explode": false,
+            "schema": {
+              "type": [
+                "array",
+                "null"
+              ],
+              "maxItems": 6,
+              "items": {
+                "type": "string",
+                "enum": [
+                  "service_charge",
+                  "single_addition_pre_tax",
+                  "single_addition_post_tax",
+                  "single_loan",
+                  "single_deduction_pre_tax",
+                  "single_deduction_post_tax"
+                ],
+                "x-clockster-set": "PayrollSingleAdjustmentsType"
+              }
+            }
+          },
+          {
+            "name": "date_from",
+            "in": "query",
+            "required": false,
+            "description": "Start of the window, inclusive (YYYY-MM-DD).",
+            "schema": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date"
+            }
+          },
+          {
+            "name": "date_to",
+            "in": "query",
+            "required": false,
+            "description": "End of the window, inclusive (YYYY-MM-DD).",
+            "schema": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "format": "date"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "user": {
+                            "type": "object",
+                            "properties": {
+                              "id": {
+                                "type": "integer"
+                              },
+                              "external_id": {
+                                "type": [
+                                  "null",
+                                  "string"
+                                ]
+                              }
+                            },
+                            "required": [
+                              "id",
+                              "external_id"
+                            ]
+                          },
+                          "type": {
+                            "type": "string"
+                          },
+                          "title": {
+                            "type": [
+                              "null",
+                              "string"
+                            ]
+                          },
+                          "amount": {
+                            "type": [
+                              "null",
+                              "number"
+                            ]
+                          },
+                          "date": {
+                            "type": "string"
+                          },
+                          "created_at": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "user",
+                          "type",
+                          "title",
+                          "amount",
+                          "date",
+                          "created_at"
+                        ]
+                      }
+                    },
+                    "links": {
+                      "$ref": "#/components/schemas/PageLinks"
+                    },
+                    "meta": {
+                      "$ref": "#/components/schemas/PageMeta"
+                    }
+                  },
+                  "required": [
+                    "data",
+                    "links",
+                    "meta"
+                  ]
+                },
+                "example": {
+                  "data": [
+                    {
+                      "id": 47809,
+                      "user": {
+                        "id": 11251,
+                        "external_id": "HR-1001"
+                      },
+                      "type": "single_addition_pre_tax",
+                      "title": "Sales bonus",
+                      "amount": 300.5,
+                      "date": "2026-03-15",
+                      "created_at": "2026-03-02T12:00:00+00:00"
+                    },
+                    {
+                      "id": 47809,
+                      "user": {
+                        "id": 11251,
+                        "external_id": "HR-1001"
+                      },
+                      "type": "single_deduction_post_tax",
+                      "title": null,
+                      "amount": 50.25,
+                      "date": "2026-03-20",
+                      "created_at": "2026-03-02T12:00:00+00:00"
+                    }
+                  ],
+                  "links": {
+                    "first": null,
+                    "last": null,
+                    "prev": null,
+                    "next": null
+                  },
+                  "meta": {
+                    "path": "https://api.clockster.com/company/v3/payroll/single-adjustments",
+                    "per_page": 50,
+                    "next_cursor": null,
+                    "prev_cursor": null
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or one this surface does not accept — code `unauthenticated`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "unauthenticated",
+                    "message": "Unauthenticated.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "A token without the company ability — code `forbidden`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "forbidden",
+                    "message": "Forbidden.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No such row in the calling company — code `not_found`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "not_found",
+                    "message": "No such resource in this company.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Refused; `error.code` says why and `error.errors` names the fields",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationRefusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "validation_failed",
+                    "message": "The per page must be at least 1.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90",
+                    "errors": {
+                      "per_page": [
+                        "The per page must be at least 1."
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limited; `Retry-After` says when — code `rate_limited`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "rate_limited",
+                    "message": "Too Many Attempts.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "description": "One-off additions and deductions, oldest first, with who they are for and the day they\nare dated.\n\n`amount` is never negative: `type` says whether it is added or taken off, and whether\nbefore or after tax. `date_from` and `date_to` bound the day, inclusive.\n\nRows filed in the web application are listed too, and may carry `13th_pay`, which is\ncomputed there rather than filed here."
+      },
+      "post": {
+        "operationId": "company.v3.payroll.single-adjustments.store",
+        "tags": [
+          "Payroll"
+        ],
+        "summary": "Create single adjustments",
+        "parameters": [
+          {
+            "name": "Idempotency-Key",
+            "in": "header",
+            "required": false,
+            "description": "A value you choose, unique per attempt. Send the same one when retrying and the first answer is replayed instead of the write happening twice. Optional, and only on the writes that carry no key of your own.",
+            "schema": {
+              "type": "string",
+              "maxLength": 255
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "user": {
+                            "type": "object",
+                            "properties": {
+                              "id": {
+                                "type": "integer"
+                              },
+                              "external_id": {
+                                "type": [
+                                  "null",
+                                  "string"
+                                ]
+                              }
+                            },
+                            "required": [
+                              "id",
+                              "external_id"
+                            ]
+                          },
+                          "type": {
+                            "type": "string"
+                          },
+                          "title": {
+                            "type": [
+                              "null",
+                              "string"
+                            ]
+                          },
+                          "amount": {
+                            "type": [
+                              "null",
+                              "number"
+                            ]
+                          },
+                          "date": {
+                            "type": "string"
+                          },
+                          "created_at": {
+                            "type": "string"
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "user",
+                          "type",
+                          "title",
+                          "amount",
+                          "date",
+                          "created_at"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "data"
+                  ]
+                },
+                "example": {
+                  "data": [
+                    {
+                      "id": 47809,
+                      "user": {
+                        "id": 11251,
+                        "external_id": "HR-1001"
+                      },
+                      "type": "single_addition_pre_tax",
+                      "title": "Sales bonus",
+                      "amount": 300.5,
+                      "date": "2026-03-15",
+                      "created_at": "2026-03-02T12:00:00+00:00"
+                    },
+                    {
+                      "id": 47809,
+                      "user": {
+                        "id": 11251,
+                        "external_id": "HR-1001"
+                      },
+                      "type": "single_deduction_post_tax",
+                      "title": null,
+                      "amount": 50.25,
+                      "date": "2026-03-20",
+                      "created_at": "2026-03-02T12:00:00+00:00"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or one this surface does not accept — code `unauthenticated`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "unauthenticated",
+                    "message": "Unauthenticated.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "A token without the company ability — code `forbidden`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "forbidden",
+                    "message": "Forbidden.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No such row in the calling company — code `not_found`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "not_found",
+                    "message": "No such resource in this company.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Refused; `error.code` says why and `error.errors` names the fields",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationRefusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "validation_failed",
+                    "message": "The per page must be at least 1.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90",
+                    "errors": {
+                      "per_page": [
+                        "The per page must be at least 1."
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limited; `Retry-After` says when — code `rate_limited`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "rate_limited",
+                    "message": "Too Many Attempts.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "description": "Up to 100 one-off amounts — a bonus, a service charge, a penalty — each for one person\nand one day. All or nothing: a `422` means none of the batch landed.\n\n**An adjustment is read when a payslip is calculated.** A `draft` payslip whose period\nholds `date` takes it in on its next calculation. An `approved` or `paid` one does not:\nit is recalculated only by hand in the web application, and nothing here tells you\nwhether that happened. Check the payslip's status for the month before filing into it.\n\n**Send an `Idempotency-Key`.** An adjustment carries no key of yours, so a retry after a\ntimeout files it a second time unless the header says it is the same attempt. The\nanswer lists what was created, in the order sent.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "adjustments": {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 100,
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "user_id": {
+                          "type": "integer",
+                          "description": "The employee this belongs to, by the id this API issued."
+                        },
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "service_charge",
+                            "single_addition_pre_tax",
+                            "single_addition_post_tax",
+                            "single_loan",
+                            "single_deduction_pre_tax",
+                            "single_deduction_post_tax"
+                          ],
+                          "x-clockster-set": "PayrollSingleAdjustmentsType",
+                          "description": "What the amount does: an addition or a deduction, before or after tax, a service charge or a one-off loan."
+                        },
+                        "amount": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 999999999,
+                          "description": "How much, never negative — `type` says which way it goes. At most two decimal places."
+                        },
+                        "date": {
+                          "type": "string",
+                          "format": "date",
+                          "description": "The day it is dated, `YYYY-MM-DD`. The payslip whose period holds this day takes it in."
+                        },
+                        "title": {
+                          "type": [
+                            "string",
+                            "null"
+                          ],
+                          "maxLength": 250,
+                          "description": "The name this is shown under."
+                        }
+                      },
+                      "required": [
+                        "user_id",
+                        "type",
+                        "amount",
+                        "date"
+                      ]
+                    },
+                    "description": "The adjustments to file, up to 100 a call."
+                  }
+                },
+                "required": [
+                  "adjustments"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "/company/v3/payroll/single-adjustments/{id}": {
+      "delete": {
+        "operationId": "company.v3.payroll.single-adjustments.destroy",
+        "tags": [
+          "Payroll"
+        ],
+        "summary": "Delete a single adjustment",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The id of the row, as this API issued it.",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/DeleteOutcome"
+                    }
+                  },
+                  "required": [
+                    "data"
+                  ]
+                },
+                "example": {
+                  "data": {
+                    "id": 47809,
+                    "result": "deleted"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "No token, or one this surface does not accept — code `unauthenticated`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "unauthenticated",
+                    "message": "Unauthenticated.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "A token without the company ability — code `forbidden`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "forbidden",
+                    "message": "Forbidden.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "No such row in the calling company — code `not_found`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "not_found",
+                    "message": "No such resource in this company.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Refused; `error.code` says why and `error.errors` names the fields",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationRefusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "validation_failed",
+                    "message": "The per page must be at least 1.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90",
+                    "errors": {
+                      "per_page": [
+                        "The per page must be at least 1."
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limited; `Retry-After` says when — code `rate_limited`",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Refusal"
+                },
+                "example": {
+                  "error": {
+                    "code": "rate_limited",
+                    "message": "Too Many Attempts.",
+                    "request_id": "9f2b1c7a-4d3e-4b8a-9f10-2c5d6e7a8b90"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "description": "Deletes the adjustment. A payslip already calculated with it keeps the amount until it\nis calculated again — for an `approved` or `paid` one, only by hand in the web\napplication.\n\nAnother company's id is a `404`."
+      }
+    },
     "/company/v3/positions": {
       "get": {
         "operationId": "company.v3.positions.index",

{clockster-0.3.0 → clockster-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "clockster"
-version = "0.3.0"
+version = "0.4.0"
 description = "Official Python SDK for the Clockster Company API"
 readme = "README.md"
 license = "MIT"

{clockster-0.3.0 → clockster-0.4.0}/src/clockster/_generated/api.py

@@ -52,6 +52,73 @@ class PayrollPayslips(_Namespace):
         )
 
 
+class PayrollSingleAdjustments(_Namespace):
+    """`clockster.payroll.single_adjustments`."""
+
+    def create(self, body: PayrollSingleAdjustmentsCreateBody, *, idempotency_key: str | None = None) -> PayrollSingleAdjustmentsCreateResponse:
+        """Create single adjustments
+
+        Up to 100 one-off amounts — a bonus, a service charge, a penalty — each for one person
+        and one day. All or nothing: a `422` means none of the batch landed.
+
+        **An adjustment is read when a payslip is calculated.** A `draft` payslip whose period
+        holds `date` takes it in on its next calculation. An `approved` or `paid` one does not:
+        it is recalculated only by hand in the web application, and nothing here tells you
+        whether that happened. Check the payslip's status for the month before filing into it.
+
+        **Send an `Idempotency-Key`.** An adjustment carries no key of yours, so a retry after a
+        timeout files it a second time unless the header says it is the same attempt. The
+        answer lists what was created, in the order sent.
+        """
+        return cast(
+            PayrollSingleAdjustmentsCreateResponse,
+            self._transport.request(
+                "POST",
+                "/company/v3/payroll/single-adjustments",
+                json=body,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    def delete(self, id: int) -> PayrollSingleAdjustmentsDeleteResponse:
+        """Delete a single adjustment
+
+        Deletes the adjustment. A payslip already calculated with it keeps the amount until it
+        is calculated again — for an `approved` or `paid` one, only by hand in the web
+        application.
+
+        Another company's id is a `404`.
+        """
+        return cast(
+            PayrollSingleAdjustmentsDeleteResponse,
+            self._transport.request(
+                "DELETE",
+                f"/company/v3/payroll/single-adjustments/{id}",
+            ),
+        )
+
+    def list(self, *, per_page: int | None = None, cursor: str | None = None, users: list[int] | None = None, types: list[PayrollSingleAdjustmentsType] | None = None, date_from: str | None = None, date_to: str | None = None) -> PayrollSingleAdjustmentsListResponse:
+        """List single adjustments
+
+        One-off additions and deductions, oldest first, with who they are for and the day they
+        are dated.
+
+        `amount` is never negative: `type` says whether it is added or taken off, and whether
+        before or after tax. `date_from` and `date_to` bound the day, inclusive.
+
+        Rows filed in the web application are listed too, and may carry `13th_pay`, which is
+        computed there rather than filed here.
+        """
+        return cast(
+            PayrollSingleAdjustmentsListResponse,
+            self._transport.request(
+                "GET",
+                "/company/v3/payroll/single-adjustments",
+                query={"per_page": per_page, "cursor": cursor, "users": users, "types": types, "date_from": date_from, "date_to": date_to},
+            ),
+        )
+
+
 class WebhooksDeliveries(_Namespace):
     """`clockster.webhooks.deliveries`."""
 
@@ -509,6 +576,7 @@ class Payroll(_Namespace):
     def __init__(self, transport: _SyncTransport) -> None:
         super().__init__(transport)
         self.payslips = PayrollPayslips(transport)
+        self.single_adjustments = PayrollSingleAdjustments(transport)
 
 
 class Positions(_Namespace):
@@ -1256,6 +1324,73 @@ class AsyncPayrollPayslips(_AsyncNamespace):
         )
 
 
+class AsyncPayrollSingleAdjustments(_AsyncNamespace):
+    """`clockster.payroll.single_adjustments`."""
+
+    async def create(self, body: PayrollSingleAdjustmentsCreateBody, *, idempotency_key: str | None = None) -> PayrollSingleAdjustmentsCreateResponse:
+        """Create single adjustments
+
+        Up to 100 one-off amounts — a bonus, a service charge, a penalty — each for one person
+        and one day. All or nothing: a `422` means none of the batch landed.
+
+        **An adjustment is read when a payslip is calculated.** A `draft` payslip whose period
+        holds `date` takes it in on its next calculation. An `approved` or `paid` one does not:
+        it is recalculated only by hand in the web application, and nothing here tells you
+        whether that happened. Check the payslip's status for the month before filing into it.
+
+        **Send an `Idempotency-Key`.** An adjustment carries no key of yours, so a retry after a
+        timeout files it a second time unless the header says it is the same attempt. The
+        answer lists what was created, in the order sent.
+        """
+        return cast(
+            PayrollSingleAdjustmentsCreateResponse,
+            await self._transport.request(
+                "POST",
+                "/company/v3/payroll/single-adjustments",
+                json=body,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    async def delete(self, id: int) -> PayrollSingleAdjustmentsDeleteResponse:
+        """Delete a single adjustment
+
+        Deletes the adjustment. A payslip already calculated with it keeps the amount until it
+        is calculated again — for an `approved` or `paid` one, only by hand in the web
+        application.
+
+        Another company's id is a `404`.
+        """
+        return cast(
+            PayrollSingleAdjustmentsDeleteResponse,
+            await self._transport.request(
+                "DELETE",
+                f"/company/v3/payroll/single-adjustments/{id}",
+            ),
+        )
+
+    async def list(self, *, per_page: int | None = None, cursor: str | None = None, users: list[int] | None = None, types: list[PayrollSingleAdjustmentsType] | None = None, date_from: str | None = None, date_to: str | None = None) -> PayrollSingleAdjustmentsListResponse:
+        """List single adjustments
+
+        One-off additions and deductions, oldest first, with who they are for and the day they
+        are dated.
+
+        `amount` is never negative: `type` says whether it is added or taken off, and whether
+        before or after tax. `date_from` and `date_to` bound the day, inclusive.
+
+        Rows filed in the web application are listed too, and may carry `13th_pay`, which is
+        computed there rather than filed here.
+        """
+        return cast(
+            PayrollSingleAdjustmentsListResponse,
+            await self._transport.request(
+                "GET",
+                "/company/v3/payroll/single-adjustments",
+                query={"per_page": per_page, "cursor": cursor, "users": users, "types": types, "date_from": date_from, "date_to": date_to},
+            ),
+        )
+
+
 class AsyncWebhooksDeliveries(_AsyncNamespace):
     """`clockster.webhooks.deliveries`."""
 
@@ -1713,6 +1848,7 @@ class AsyncPayroll(_AsyncNamespace):
     def __init__(self, transport: _AsyncTransport) -> None:
         super().__init__(transport)
         self.payslips = AsyncPayrollPayslips(transport)
+        self.single_adjustments = AsyncPayrollSingleAdjustments(transport)
 
 
 class AsyncPositions(_AsyncNamespace):

{clockster-0.3.0 → clockster-0.4.0}/src/clockster/_generated/models.py

@@ -83,6 +83,16 @@ __all__ = [
     "PayrollPayslipsListRowSalary",
     "PayrollPayslipsListRowUser",
     "PayrollPayslipsStatus",
+    "PayrollSingleAdjustmentsCreateAdjustment",
+    "PayrollSingleAdjustmentsCreateBody",
+    "PayrollSingleAdjustmentsCreateResponse",
+    "PayrollSingleAdjustmentsCreateRow",
+    "PayrollSingleAdjustmentsCreateRowUser",
+    "PayrollSingleAdjustmentsDeleteResponse",
+    "PayrollSingleAdjustmentsListResponse",
+    "PayrollSingleAdjustmentsListRow",
+    "PayrollSingleAdjustmentsListRowUser",
+    "PayrollSingleAdjustmentsType",
     "PositionsDeleteResponse",
     "PositionsGetData",
     "PositionsGetResponse",
@@ -239,6 +249,8 @@ LocationsInclude = Literal["managers"]
 
 PayrollPayslipsStatus = Literal["draft", "approved", "paid"]
 
+PayrollSingleAdjustmentsType = Literal["service_charge", "single_addition_pre_tax", "single_addition_post_tax", "single_loan", "single_deduction_pre_tax", "single_deduction_post_tax"]
+
 SchedulesLeaveType = Literal["annual", "unpaid", "sick", "unpaid_sick", "maternity", "paternity", "special", "day_off", "compensatory", "personal", "emergency", "unexcused_absence"]
 
 SchedulesType = Literal["work", "free", "leave"]
@@ -798,6 +810,60 @@ class PayrollPayslipsListMeta(TypedDict):
     next_cursor: str | None
     prev_cursor: str | None
 
+class PayrollSingleAdjustmentsListResponse(TypedDict):
+    data: list[PayrollSingleAdjustmentsListRow]
+    links: PageLinks
+    meta: PageMeta
+
+class PayrollSingleAdjustmentsListRow(TypedDict):
+    id: int
+    user: PayrollSingleAdjustmentsListRowUser
+    type: str
+    title: str | None
+    amount: float | None
+    date: str
+    created_at: str
+
+class PayrollSingleAdjustmentsListRowUser(TypedDict):
+    id: int
+    external_id: str | None
+
+class PayrollSingleAdjustmentsCreateResponse(TypedDict):
+    data: list[PayrollSingleAdjustmentsCreateRow]
+
+class PayrollSingleAdjustmentsCreateRow(TypedDict):
+    id: int
+    user: PayrollSingleAdjustmentsCreateRowUser
+    type: str
+    title: str | None
+    amount: float | None
+    date: str
+    created_at: str
+
+class PayrollSingleAdjustmentsCreateRowUser(TypedDict):
+    id: int
+    external_id: str | None
+
+class PayrollSingleAdjustmentsCreateBody(TypedDict):
+    # The adjustments to file, up to 100 a call.
+    adjustments: list[PayrollSingleAdjustmentsCreateAdjustment]
+
+class PayrollSingleAdjustmentsCreateAdjustment(TypedDict):
+    # The employee this belongs to, by the id this API issued.
+    user_id: int
+    # What the amount does: an addition or a deduction, before or after tax, a service charge or a
+    # one-off loan.
+    type: PayrollSingleAdjustmentsType
+    # How much, never negative — `type` says which way it goes. At most two decimal places.
+    amount: float
+    # The day it is dated, `YYYY-MM-DD`. The payslip whose period holds this day takes it in.
+    date: str
+    # The name this is shown under.
+    title: NotRequired[str | None]
+
+class PayrollSingleAdjustmentsDeleteResponse(TypedDict):
+    data: DeleteOutcome
+
 class PositionsListResponse(TypedDict):
     data: list[PositionsListRow]
     links: PageLinks