repzo 1.0.290 → 1.0.292

package/src/oas/day-shift.yaml

@@ -0,0 +1,415 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - Day Shift
+  version: 1.0.0
+  description: |
+    **Day shifts** are reusable weekly work schedules assigned to sales reps.
+    Each shift holds a `schedule[]` of per-weekday entries
+    (`{ day, work_time[] }`); every `work_time` range is a `HH:mm` wall-clock
+    interval in the company time zone, and a range whose `to <= from` crosses
+    midnight into the next calendar date (e.g. `18:00 → 02:00`).
+
+    **Why it matters.** Repzo keys all daily data on a **business-day string**
+    (`"2026-07-14"`), derived from a per-company `end_of_day` cut. A shift acts
+    as a **per-weekday override of that cut**: yesterday's overnight spill can
+    raise the boundary (so early-morning activity still belongs to the prior
+    working day) and today's early shift start can pull it down. When a rep has
+    **no shift assigned**, business-day resolution is byte-identical to the
+    legacy company `end_of_day` behaviour. See the shift-aware resolver in
+    `src/util.ts` (`resolveBusinessDay`, `findDay`, `findTimeFrame`).
+
+    **Assignment.** A rep is assigned a shift through the rep's own
+    `assigned_shift` field (see the Rep service). The resolved schedule is
+    snapshotted onto the rep's `day` document at day-open — together with the
+    business-day context it was stamped with (`EOD`, `timeZone`) — and every
+    business-day stamping site (visits, activities, day close/recalc,
+    transactional documents) resolves against that full snapshot while the
+    day is open: neither a mid-day shift reassignment / schedule edit nor an
+    owner changing the company `end_of_day` / `time_zone` moves an in-flight
+    day's boundaries or stamps new documents onto a different business day
+    than the open day. The rep's current shift and the namespace's current
+    settings only apply when no day is open (i.e. from the next day-open
+    onward).
+
+    **Who calls it.** Admins manage shifts from the back-office UI. Reps are
+    notified of changes via the `update-day-shift` command (real-time push).
+
+    **Multi-tenancy & lifecycle.** Records are scoped by `company_namespace[]`
+    (server-injected from session). Soft-delete via `disabled: true`; deletion
+    is rejected while any active rep's `assigned_shift` still points at the
+    shift. `designation` is an optional free-text label. `name` is unique per
+    namespace among active rows (compound unique index
+    `(company_namespace, name)`, partial on `disabled: false`).
+
+    **Validation.** On create/update the `schedule` is validated so business-day
+    resolution stays well-defined: each weekday appears at most once; every
+    range has a valid, non-equal `from`/`to`; per day, ranges are
+    non-overlapping and only the **last** range may cross midnight; a day's
+    overnight tail must not overlap the next weekday's earliest start; and,
+    against the namespace's `end_of_day`, no weekday's business day may be
+    eliminated — a shift whose end reaches or passes the FOLLOWING weekday's
+    end-of-day cut while that weekday has no ranges (e.g. `end_of_day` 12:00
+    with Monday 22:00→13:00 and Tuesday off) is rejected, since the label in
+    between could never own a single instant.
+
+    **Key relationships.** Referenced by `representatives` via the rep's
+    `assigned_shift` field.
+
+    **Events.** Create / update / remove emit `update-day-shift`, which notifies
+    reps in the namespace. Bulk `patch` is not supported.
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /day-shift:
+    get:
+      summary: Find day shifts
+      operationId: findDayShifts
+      parameters:
+        - in: query
+          name: _id
+          description: |
+            "Filter by shift `_id`. Pass once for a single match, or as
+            `?_id[]=...&_id[]=...` for multiple."
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: name
+          description: |
+            Exact-match on shift `name` **or** `designation` (the value is
+            expanded to match either field).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: designation
+          description: Exact-match on shift `designation`.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: disabled
+          description: Include disabled (soft-deleted) shifts. Defaults to `false`.
+          schema: { type: boolean, default: false }
+        - in: query
+          name: from_updatedAt
+          description: |
+            Cursor — return only shifts with `updatedAt` greater than this Unix
+            timestamp (ms). Used by sync clients.
+          schema: { type: number }
+        - in: query
+          name: inject_assigned_reps
+          description: |
+            When truthy, each returned shift is enriched with an
+            `assigned_reps[]` array (`_id`, `name`) of the active reps whose
+            `assigned_shift` points at it.
+          schema: { type: boolean, default: false }
+        - in: query
+          name: from__id
+          description: Cursor — return records with `_id` greater than this value.
+          schema: { type: string }
+        - in: query
+          name: to__id
+          description: Cursor — return records with `_id` less than this value.
+          schema: { type: string }
+        - in: query
+          name: per_page
+          description: Page size. Defaults to the server's configured pagination limit.
+          schema: { type: integer, minimum: 1, maximum: 500 }
+          example: 50
+        - in: query
+          name: page
+          description: 1-indexed page number.
+          schema: { type: integer, minimum: 1 }
+          example: 1
+        - in: query
+          name: sortBy
+          description: |
+            Sort directives. Encoded with `qs` bracket notation, e.g.
+            `?sortBy[0][field]=_id&sortBy[0][type]=desc`.
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                field:
+                  type: string
+                  enum: [_id]
+                type:
+                  type: string
+                  enum: [asc, desc]
+      responses:
+        "200":
+          description: Paginated list of shifts.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ShiftFindResult"
+    post:
+      summary: Create a day shift
+      description: |
+        Creates a shift. The `schedule` is validated (see the service
+        description). Emits `update-day-shift`.
+      operationId: createDayShift
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ShiftCreateBody"
+      responses:
+        "201":
+          description: The newly-created shift document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ShiftSchema"
+  /day-shift/{id}:
+    get:
+      summary: Get a day shift by id
+      operationId: getDayShift
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The shift document for the given `_id`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ShiftSchema"
+    put:
+      summary: Update a day shift
+      description: |
+        Standard put. When `schedule` is present it is validated. Setting
+        `disabled: true` soft-deletes the shift and — like DELETE — is
+        rejected with a `BadRequest` while any active rep's `assigned_shift`
+        still points at it. Emits `update-day-shift`.
+      operationId: updateDayShift
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ShiftUpdateBody"
+      responses:
+        "200":
+          description: The shift document after the update is applied.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ShiftSchema"
+    delete:
+      summary: Soft-delete a day shift
+      description: |
+        Soft-deletes the shift (`disabled: true`). Rejected with a
+        `BadRequest` while any active rep's `assigned_shift` still points at
+        it. Emits `update-day-shift`.
+      operationId: removeDayShift
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: "The shift document after soft-deletion (`disabled: true`)."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ShiftSchema"
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: api-key
+      description: |
+        Server-issued API key. Also accepted via the `x-api-key` header or the
+        `?apiKey=` query parameter as fallbacks.
+    JwtAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: |
+        Raw JWT in the `Authorization` header — **no `Bearer ` prefix**.
+        Obtained from `POST /authenticate` (admin / rep / client login).
+  schemas:
+    ShiftRange:
+      type: object
+      description: |
+        A single work interval in `HH:mm` wall-clock time (company time zone).
+        A range whose `to <= from` crosses midnight into the next calendar date.
+      required:
+        - from
+        - to
+      properties:
+        from:
+          type: string
+          pattern: "^([01]\\d|2[0-3]):[0-5]\\d$"
+          example: "18:00"
+        to:
+          type: string
+          pattern: "^([01]\\d|2[0-3]):[0-5]\\d$"
+          example: "02:00"
+    ShiftEntry:
+      type: object
+      description: One weekday's work_time ranges.
+      required:
+        - day
+        - work_time
+      properties:
+        day:
+          type: string
+          enum: [sunday, monday, tuesday, wednesday, thursday, friday, saturday]
+        work_time:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/ShiftRange"
+    ShiftSchema:
+      type: object
+      description: Shift document.
+      properties:
+        _id:
+          type: string
+          description: Unique identifier for the shift.
+        name:
+          type: string
+          description: Display name.
+        designation:
+          type: string
+          description: Optional free-text label for the shift.
+        disabled:
+          type: boolean
+          description: Soft-delete flag.
+        schedule:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/ShiftEntry"
+          description: Weekly work schedule (per-weekday work_time ranges).
+        total_working_hours:
+          type: number
+          description: |
+            Server-computed total working hours across the schedule
+            (cross-midnight ranges counted correctly). Derived on write.
+        total_working_days:
+          type: number
+          description: |
+            Server-computed count of weekdays with at least one work_time
+            range. Derived on write.
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Tenant key. Server-injected — never accept from clients.
+        createdAt:
+          type: string
+          format: date-time
+          description: Creation timestamp.
+        updatedAt:
+          type: string
+          format: date-time
+          description: Last update timestamp.
+    ShiftCreateBody:
+      type: object
+      description: |
+        Body for creating a shift. The tenant key (`company_namespace`) is
+        optional for SDK callers and is otherwise injected from the caller's
+        session. `schedule` is validated on write.
+      required:
+        - name
+        - schedule
+      properties:
+        name:
+          type: string
+          description: Display name.
+        designation:
+          type: string
+          description: Optional free-text label for the shift.
+        schedule:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/ShiftEntry"
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Optional tenant namespace override for SDK callers.
+    ShiftUpdateBody:
+      type: object
+      description: |
+        Body for updating a shift. The tenant key (`company_namespace`) is
+        derived from the caller's session — do not send it. When `schedule` is
+        present it is validated. Set `disabled: true` to soft-delete.
+      properties:
+        name:
+          type: string
+        designation:
+          type: string
+        schedule:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/ShiftEntry"
+        disabled:
+          type: boolean
+          description: |
+            Soft-delete flag. Set to `true` to disable the shift — rejected
+            while any active rep is still assigned to it.
+    ShiftFindResult:
+      type: object
+      description: Standard paginated result envelope.
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/ShiftSchema"
+        total_result:
+          type: number
+          description: Total number of shifts matching the filter.
+        current_count:
+          type: number
+          description: Count of shifts on the current page.
+        total_pages:
+          type: number
+          description: Total number of pages.
+        current_page:
+          type: number
+          description: Current page number.
+        per_page:
+          type: number
+          description: Number of shifts per page.
+        first_page_url:
+          type: string
+          description: URL for the first page.
+        last_page_url:
+          type: string
+          description: URL for the last page.
+        next_page_url:
+          type: string
+          nullable: true
+          description: URL for the next page.
+        prev_page_url:
+          type: string
+          nullable: true
+          description: URL for the previous page.
+        path:
+          type: string
+          description: Base URL path.

package/src/oas/day.yaml

@@ -30,12 +30,20 @@ paths:
                     items:
                       type: string
                   - type: string
+              reps:
+                oneOf:
+                  - type: array
+                    items:
+                      type: string
+                  - type: string
               date:
                 type: string
                 format: date
               status:
                 type: string
                 enum: [open, closed, submitted]
+              not_working_day:
+                type: boolean
               from_date:
                 type: string
                 format: date
@@ -151,6 +159,9 @@ components:
           type: string
           enum: [open, closed, submitted]
           description: Status of the day
+        not_working_day:
+          type: boolean
+          description: Server-set flag for days that fall on a scheduled day off of the rep's assigned shift.
         visits:
           type: array
           items:

package/src/oas/rep.yaml

@@ -147,6 +147,12 @@ paths:
                     items:
                       type: string
                   - type: string
+              assigned_shift:
+                oneOf:
+                  - type: array
+                    items:
+                      type: string
+                  - type: string
               media:
                 oneOf:
                   - type: array
@@ -172,6 +178,7 @@ paths:
                       "assigned_plan",
                       "assigned_retail_execution_templates",
                       "assigned_geo_zones",
+                      "assigned_shift",
                       "warehouse",
                     ]
               withProductLines:
@@ -329,6 +336,12 @@ paths:
                 type: boolean
               "permissions.rep_must_end_day_after_specific_time":
                 type: boolean
+              "permissions.rep_must_start_day_within_shift_window":
+                type: boolean
+              "permissions.rep_must_end_day_within_shift_window":
+                type: boolean
+              "permissions.rep_can_start_day_on_non_working_day":
+                type: boolean
               "permissions.rep_can_create_negative_invoice":
                 type: boolean
               "settings.rep_must_end_day_after":
@@ -360,6 +373,12 @@ paths:
                 type: boolean
               "settings.watermark_coordinates":
                 type: boolean
+              "settings.start_day_minutes_before_shift_start":
+                type: number
+              "settings.start_day_minutes_after_shift_start":
+                type: number
+              "settings.end_day_minutes_before_shift_end":
+                type: number
           description: Query parameters for filtering reps
       responses:
         "200":
@@ -738,6 +757,15 @@ components:
             rep_must_end_day_after_specific_time:
               type: boolean
               description: Rep must end day after specific time
+            rep_must_start_day_within_shift_window:
+              type: boolean
+              description: When true, the rep may only open the day within the configured window around the assigned shift start.
+            rep_must_end_day_within_shift_window:
+              type: boolean
+              description: When true, the rep may only end the day from the configured offset before the assigned shift end.
+            rep_can_start_day_on_non_working_day:
+              type: boolean
+              description: When false, opening a day on an assigned-shift day off is rejected.
             rep_can_create_negative_invoice:
               type: boolean
               description: Rep can create negative invoice
@@ -861,6 +889,10 @@ components:
           items:
             type: string
           description: Assigned retail execution templates
+        assigned_shift:
+          type: string
+          nullable: true
+          description: "`_id` of the day-shift assigned to this rep (ref `day-shift`). `null` when unassigned."
         customFields:
           type: object
           additionalProperties:
@@ -926,6 +958,24 @@ components:
               type: string
               pattern: "^[0-9]{1,2}:[0-9]{2}$"
               description: Time rep must end day after (HH:MM format)
+            start_day_minutes_before_shift_start:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes before the assigned shift start from which the rep may open the day.
+            start_day_minutes_after_shift_start:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes after the assigned shift start until which the rep may open the day when shift-window enforcement is enabled.
+            end_day_minutes_before_shift_end:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes before the assigned shift end from which the rep may close the day when shift-window enforcement is enabled.
         integration_meta:
           type: object
           additionalProperties: true
@@ -1199,6 +1249,15 @@ components:
             rep_must_end_day_after_specific_time:
               type: boolean
               description: Rep must end day after specific time
+            rep_must_start_day_within_shift_window:
+              type: boolean
+              description: When true, the rep may only open the day within the configured window around the assigned shift start.
+            rep_must_end_day_within_shift_window:
+              type: boolean
+              description: When true, the rep may only end the day from the configured offset before the assigned shift end.
+            rep_can_start_day_on_non_working_day:
+              type: boolean
+              description: When false, opening a day on an assigned-shift day off is rejected.
             rep_can_create_negative_invoice:
               type: boolean
               description: Rep can create negative invoice
@@ -1322,6 +1381,10 @@ components:
           items:
             type: string
           description: Assigned retail execution templates
+        assigned_shift:
+          type: string
+          nullable: true
+          description: "`_id` of the day-shift to assign to this rep (ref `day-shift`). Must reference an existing, active shift in the caller's namespace. Send `null` to clear the assignment."
         customFields:
           type: object
           additionalProperties:
@@ -1387,6 +1450,24 @@ components:
               type: string
               pattern: "^[0-9]{1,2}:[0-9]{2}$"
               description: Time rep must end day after (HH:MM format)
+            start_day_minutes_before_shift_start:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes before the assigned shift start from which the rep may open the day.
+            start_day_minutes_after_shift_start:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes after the assigned shift start until which the rep may open the day when shift-window enforcement is enabled.
+            end_day_minutes_before_shift_end:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes before the assigned shift end from which the rep may close the day when shift-window enforcement is enabled.
         integration_meta:
           type: object
           additionalProperties: true
@@ -1650,6 +1731,15 @@ components:
             rep_must_end_day_after_specific_time:
               type: boolean
               description: Rep must end day after specific time
+            rep_must_start_day_within_shift_window:
+              type: boolean
+              description: When true, the rep may only open the day within the configured window around the assigned shift start.
+            rep_must_end_day_within_shift_window:
+              type: boolean
+              description: When true, the rep may only end the day from the configured offset before the assigned shift end.
+            rep_can_start_day_on_non_working_day:
+              type: boolean
+              description: When false, opening a day on an assigned-shift day off is rejected.
             rep_can_create_negative_invoice:
               type: boolean
               description: Rep can create negative invoice
@@ -1773,6 +1863,10 @@ components:
           items:
             type: string
           description: Assigned retail execution templates
+        assigned_shift:
+          type: string
+          nullable: true
+          description: "`_id` of the day-shift to assign to this rep (ref `day-shift`). Must reference an existing, active shift in the caller's namespace. Send `null` to clear the assignment."
         customFields:
           type: object
           additionalProperties:
@@ -1838,6 +1932,24 @@ components:
               type: string
               pattern: "^[0-9]{1,2}:[0-9]{2}$"
               description: Time rep must end day after (HH:MM format)
+            start_day_minutes_before_shift_start:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes before the assigned shift start from which the rep may open the day.
+            start_day_minutes_after_shift_start:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes after the assigned shift start until which the rep may open the day when shift-window enforcement is enabled.
+            end_day_minutes_before_shift_end:
+              type: number
+              minimum: 0
+              maximum: 240
+              default: 0
+              description: Minutes before the assigned shift end from which the rep may close the day when shift-window enforcement is enabled.
         integration_meta:
           type: object
           additionalProperties: true

package/src/oas/settings.yaml

@@ -93,6 +93,27 @@ components:
           type: string
         description:
           type: string
+        calculate_target_for_non_working_days:
+          type: boolean
+          default: false
+          description: "When true, system-created absent days that fall on a scheduled day off of the rep's assigned shift still trigger target calculation."
+        end_of_day:
+          type: string
+          description: "Per-namespace day-cutover time as HH:mm. Propagated to company-namespaces.end_of_day."
+        time_zone:
+          type: string
+          description: "Per-namespace IANA time zone. Propagated to company-namespaces.time_zone."
+        end_of_day_mode:
+          type: string
+          enum: [fixed_time, shift_based]
+          default: fixed_time
+          description: "How the namespace determines the end-of-day cutover: fixed_time uses the company end_of_day setting; shift_based derives it from assigned day shifts."
+        automatic_end_day_minutes_after_shift_end:
+          type: integer
+          minimum: 0
+          maximum: 240
+          default: 0
+          description: "Shift-based mode only: minutes after a shift-based day's shift end before the system auto-closes it."
         start_day_outside_active_zone_action:
           type: string
           enum: [monitor, warning, block]
@@ -145,6 +166,21 @@ components:
           type: string
         description:
           type: string
+        calculate_target_for_non_working_days:
+          type: boolean
+          default: false
+          description: "When true, system-created absent days that fall on a scheduled day off of the rep's assigned shift still trigger target calculation."
+        end_of_day_mode:
+          type: string
+          enum: [fixed_time, shift_based]
+          default: fixed_time
+          description: "How the namespace determines the end-of-day cutover: fixed_time uses the company end_of_day setting; shift_based derives it from assigned day shifts."
+        automatic_end_day_minutes_after_shift_end:
+          type: integer
+          minimum: 0
+          maximum: 240
+          default: 0
+          description: "Shift-based mode only: minutes after a shift-based day's shift end before the system auto-closes it."
         start_day_outside_active_zone_action:
           type: string
           enum: [monitor, warning, block]