repzo 1.0.292 → 1.0.293

package/src/oas/ai-object-detection-label.yaml

@@ -0,0 +1,395 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Label
+  version: 1.0.0
+  description: |
+    Defines **object-detection label classes** — a named class (with an optional
+    annotation `keyboard_shortcut` and a reference crop `media_photo`) linked to
+    the products / variants / brands / categories / sub-categories / groups it
+    represents. Labels are the vocabulary every other object-detection service
+    speaks: datasets group them (`ai-object-detection-dataset`), task
+    annotations point at them, categories and segments list them, and the label
+    report (`ai-object-detection-label-report`) measures their annotation
+    health.
+
+    **Dims reclassifier inputs.** `label_group` places the label in a family of
+    sibling labels (size / flavour variants of one line); a detection may only
+    be re-labelled BETWEEN labels sharing a group. `physical_size` (`w_cm`,
+    `h_cm`, centimetres) is the expected front-face size — optional, and the
+    reclassifier skips labels without it. It can be filled by hand or from the
+    label report's `mode=dims` smart analyzer.
+
+    **Who calls it.** Back-office admins (label screen). Scoped by
+    `company_namespace[]` (injected from the caller's session); `name` is
+    unique per namespace and must match `^[a-zA-Z_][a-zA-Z0-9_\s]*$`.
+    Soft-delete via `disabled`; `DELETE` is blocked while any dataset still
+    lists the label in `dataset_labels`. Creating or updating a label with a
+    `media_photo` links that media document to the label so it is not swept as
+    orphaned media. `PATCH` is not allowed (400).
+
+    **Population.** `populatedKeys[]` on find/get embeds the linked documents
+    under `<field>_populated` (`label_group`, `media_photo`, `variants`,
+    `products`, `product_categories`, `product_subcategories`,
+    `product_brands`, `product_groups`).
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-label:
+    get:
+      summary: Find labels
+      operationId: findAiObjectDetectionLabels
+      parameters:
+        - in: query
+          name: _id
+          description: Filter by label `_id`. Pass once or as `?_id[]=...` for multiple.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: name
+          description: Exact-match on `name` (single value or list).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: search
+          description: Case-insensitive substring / regex match on `name`.
+          schema: { type: string }
+          example: heinz
+        - in: query
+          name: label_group
+          description: Filter by `ai-object-detection-label-group` id(s).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: variants
+          description: Filter by linked variant id(s) — pass once or as `?variants[]=`.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: products
+          description: Filter by linked product id(s).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: product_categories
+          description: Filter by linked product category id(s).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: product_subcategories
+          description: Filter by linked product sub-category id(s).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: product_brands
+          description: Filter by linked product brand id(s).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: product_groups
+          description: Filter by linked product group id(s).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: disabled
+          description: "`true` returns only soft-deleted labels, `false` only live ones. Omitted returns both."
+          schema: { type: boolean }
+        - in: query
+          name: from_updatedAt
+          description: Return labels with `updatedAt` on/after this Unix timestamp (ms); snapped to start of day unless `exact_time=true`.
+          schema: { type: number }
+        - in: query
+          name: to_updatedAt
+          description: Return labels with `updatedAt` on/before this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: from_createdAt
+          description: Return labels with `createdAt` on/after this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: to_createdAt
+          description: Return labels with `createdAt` on/before this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: populatedKeys
+          description: Joins to embed under `<field>_populated`.
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - label_group
+                - media_photo
+                - variants
+                - products
+                - product_categories
+                - product_subcategories
+                - product_brands
+                - product_groups
+        - in: query
+          name: per_page
+          description: Page size (capped by the server's pagination max).
+          schema: { type: integer, minimum: 1 }
+          example: 20
+        - in: query
+          name: page
+          description: 1-based page number.
+          schema: { type: integer, minimum: 1 }
+          example: 1
+        - in: query
+          name: sort
+          description: Field to sort by. Defaults to `_id`.
+          schema: { type: string, default: _id }
+        - in: query
+          name: sortPageOrder
+          description: Sort direction. Defaults to descending.
+          schema: { type: string, enum: [asc, dsc], default: dsc }
+      responses:
+        "200":
+          description: Paginated list of labels.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OdLabelFindResult"
+    post:
+      summary: Create a label
+      description: "Creates a label. When `media_photo` is set the media document is linked to the new label. `name` must be unique per namespace."
+      operationId: createAiObjectDetectionLabel
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OdLabelCreateBody"
+      responses:
+        "201":
+          description: The created label.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OdLabelSchema"
+  /ai-object-detection-label/{id}:
+    get:
+      summary: Get a label by id
+      operationId: getAiObjectDetectionLabel
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+        - in: query
+          name: populatedKeys
+          description: Joins to embed under `<field>_populated` (same set as on find).
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - label_group
+                - media_photo
+                - variants
+                - products
+                - product_categories
+                - product_subcategories
+                - product_brands
+                - product_groups
+      responses:
+        "200":
+          description: The label.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OdLabelSchema"
+        "400":
+          description: No label with that id in the caller's namespace.
+    put:
+      summary: Update a label
+      description: "Standard put (mongoose `updateOne` with validators). Set `disabled: true` to soft-delete. If the result carries a `media_photo` the media document is (re-)linked to the label."
+      operationId: updateAiObjectDetectionLabel
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OdLabelUpdateBody"
+      responses:
+        "200":
+          description: The label after the update.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OdLabelSchema"
+        "404":
+          description: No label with that id in the caller's namespace.
+    delete:
+      summary: Soft-delete a label
+      description: "Sets `disabled: true`. Rejected with 400 while the label is listed in any dataset's `dataset_labels` — remove it from those datasets first."
+      operationId: removeAiObjectDetectionLabel
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: The label after soft-deletion.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OdLabelSchema"
+        "400":
+          description: The label is still associated with one or more datasets, or was not found.
+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:
+    OdLabelPhysicalSize:
+      type: object
+      description: Expected physical front-face size in centimetres. Each axis accepts 0.1–500.
+      properties:
+        w_cm: { type: number, minimum: 0.1, maximum: 500 }
+        h_cm: { type: number, minimum: 0.1, maximum: 500 }
+    OdLabelSchema:
+      type: object
+      properties:
+        _id: { type: string }
+        name:
+          type: string
+          description: "Unique per namespace; must match `^[a-zA-Z_][a-zA-Z0-9_\\s]*$`."
+        keyboard_shortcut:
+          type: string
+          description: "Annotation hot-key — one lower-case letter or digit, excluding `i`, `o` and `_`."
+        media_photo:
+          type: string
+          description: Reference crop media id.
+        products: { type: array, items: { type: string } }
+        variants: { type: array, items: { type: string } }
+        product_brands: { type: array, items: { type: string } }
+        product_categories: { type: array, items: { type: string } }
+        product_subcategories: { type: array, items: { type: string } }
+        product_groups: { type: array, items: { type: string } }
+        label_group:
+          type: string
+          description: "`ai-object-detection-label-group` id — sibling family for the dims reclassifier."
+        physical_size:
+          $ref: "#/components/schemas/OdLabelPhysicalSize"
+        disabled: { type: boolean }
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Tenant key (server-injected).
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+    OdLabelCreateBody:
+      type: object
+      description: "Body for creating a label. `company_namespace` is optional for SDK callers and otherwise injected from the caller's session."
+      required: [name]
+      properties:
+        name:
+          type: string
+          description: "Unique per namespace; must match `^[a-zA-Z_][a-zA-Z0-9_\\s]*$`."
+        keyboard_shortcut:
+          type: string
+          description: "One lower-case letter or digit, excluding `i`, `o` and `_`."
+        media_photo:
+          type: string
+          description: Reference crop media id (linked to the label on save).
+        products: { type: array, items: { type: string } }
+        variants: { type: array, items: { type: string } }
+        product_brands: { type: array, items: { type: string } }
+        product_categories: { type: array, items: { type: string } }
+        product_subcategories: { type: array, items: { type: string } }
+        product_groups: { type: array, items: { type: string } }
+        label_group:
+          type: string
+          description: "`ai-object-detection-label-group` id."
+        physical_size:
+          $ref: "#/components/schemas/OdLabelPhysicalSize"
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Optional tenant namespace override for SDK callers.
+    OdLabelUpdateBody:
+      type: object
+      description: "Body for updating a label. `company_namespace` is derived from the caller's session — do not send it. Set `disabled: true` to soft-delete."
+      properties:
+        name: { type: string }
+        keyboard_shortcut: { type: string }
+        media_photo: { type: string }
+        products: { type: array, items: { type: string } }
+        variants: { type: array, items: { type: string } }
+        product_brands: { type: array, items: { type: string } }
+        product_categories: { type: array, items: { type: string } }
+        product_subcategories: { type: array, items: { type: string } }
+        product_groups: { type: array, items: { type: string } }
+        label_group: { type: string }
+        physical_size:
+          $ref: "#/components/schemas/OdLabelPhysicalSize"
+        disabled:
+          type: boolean
+          description: Soft-delete flag.
+    OdLabelFindResult:
+      type: object
+      description: Standard paginated result envelope.
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/OdLabelSchema"
+        total_result: { type: number }
+        current_count: { type: number }
+        total_pages: { type: number }
+        current_page: { type: number }
+        per_page: { type: number }
+        first_page_url: { type: string }
+        last_page_url: { type: string }
+        next_page_url: { type: string, nullable: true }
+        prev_page_url: { type: string, nullable: true }
+        path: { type: string }