mirror of
https://github.com/Sea-Haven-Industries/procurement-ingest.git
synced 2026-09-30 13:03:14 +00:00
f67d8b9907
Some checks are pending
Deploy / deploy (push) Waiting to run
* feat(api): add procurement-api stack - read API + OpenAPI docs page Third CDK stack: API Gateway REST API (IAM SigV4) over both pipelines' tables, replacing SHOC's retired SyncController cross-account DynamoDB scan as the reconciliation/backfill path. - lambdas/api/: handler (healthcheck + docs-token gate + router dispatch), router (single route table), pagination (opaque cursor, hostile -> 400), Decimal-safe serialization, wo_repo/po_repo reads. No VendorReplies. - OpenAPI 3.1 spec as source of truth incl. top-level webhooks section documenting the outbound SHOC feed; phase-2 write endpoints x-planned (router answers 501). Self-contained /docs page, no CDN. - Auth: AWS_IAM on data routes + resource policy scoped to exactly arn:aws:iam::396287094661:role/shoc-backend-dev on GET/*; /docs and /openapi.json carve-out is token-gated in the Lambda via shared web_ui_auth (fail-closed, INFRA-74 posture). - KMS: explicit Decrypt/DescribeKey on the DynamoDB CMK from SSM (name-imported table drops the key association - INFRA-104 class). - Alarms: errors/throttles/duration(p99>=22.5s) + gateway 5xx, ALARM-only to site-alerts. No access logging in v1 (docs ?token= shim stays out of logs); cloud_watch_role=False. - Tests: handler auth-seam + routing + Decimal round-trip; moto cursor pagination incl. hostile cursors; spec<->router drift gate; bundle AST pins for the api command; pytest.ini --cov + loader siblings. - Deploy role: third stack DescribeStacks ARN + procurement-api smoke invoke ARN (re-run create-deploy-role.sh before merge). * harden(api): apply sh-security-review findings to procurement-api Fan-out (6 detectors) + review findings resolved: Correctness / DoS: - pagination: require EXACT key-set match (was subset) so a partial/foreign composite cursor can't reach DynamoDB as an inconsistent ExclusiveStartKey -> ValidationException -> 500; comments Query now pins the cursor's work_order_id to the path entity. - handler: map botocore ValidationException to 400 (defense in depth) so a crafted cursor can't drive the zero-threshold 5xx alarm. - web_ui_auth: compare tokens as bytes; a non-ASCII presented token now fails closed (401) instead of crashing hmac.compare_digest into a 500. Resolves the pre-existing xfail(strict) follow-up test; hardens the web UIs too. Docs page: - typeStr() now escapes the one spec-derived string that reached innerHTML. - spec inlined into the docs <script> block escapes "<" -> < (</script> breakout guard); /openapi.json still served byte-faithful. - Cache-Control: no-store + Referrer-Policy: no-referrer on docs responses so the ?token= URL stays out of caches/Referer. - spec-drift test asserts the committed spec carries no "</" / "<!--". IAM / IaC: - resource policy enumerates the 7 data GET resources instead of GET/* so a future GET route can't silently inherit SHOC cross-account reach. - kms:Decrypt grant gains a kms:ViaService=dynamodb condition. - stage throttling (50 rps / 100 burst) bounds the unauthenticated /docs blast radius below the 10k account default. - corrected the PATCH/POST comment (same-account callers aren't blocked by the resource policy; 501 handler + absent write grant are the gate). - documented the RETAIN log-group first-deploy rollback trap and the resource-policy-needs-redeploy gotcha in-stack. Mandatory GPT-4.1 cross-family review of the full policy surface: no BLOCK/FIX. 675 tests pass, ruff clean, cdk synth green.
1022 lines
31 KiB
JSON
1022 lines
31 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Procurement Ingest API",
|
|
"version": "1.0.0",
|
|
"description": "Read API over the procurement-ingest pipelines (work orders + purchase orders), plus the outbound SHOC work-order webhook feed (see `webhooks`).\n\n**Purpose:** reconciliation and backfill for downstream consumers (primarily SHOC) - this API replaces SHOC's retired SyncController DynamoDB scan. Listings are **unordered** paginated scans: follow `next_cursor` until it is `null`. `cursor` is opaque; a malformed cursor returns `400`. Field names mirror the DynamoDB attributes written by the pipelines (source of truth: `lambdas/wo/email_processor/persistence.py` and `lambdas/po/email_processor/persistence.py`).\n\n**Auth:** data endpoints require AWS IAM SigV4 (service `execute-api`, region `us-east-1`); cross-account callers must also be allowed by the API resource policy. `/docs` and `/openapi.json` use the shared docs token instead (header `X-Auth-Token`, or `?token=` in a browser). No CORS is configured (server-to-server and Postman callers only).\n\n**Write endpoints** marked `x-planned` are phase 2: documented here for contract visibility, the API answers `501` until they ship."
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://{apiId}.execute-api.us-east-1.amazonaws.com/prod",
|
|
"description": "seahaven-prod (011934824531). The concrete apiId is in the procurement-api stack output ApiEndpointUrl.",
|
|
"variables": {
|
|
"apiId": {
|
|
"default": "SEE-STACK-OUTPUT"
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"sigv4": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/work-orders": {
|
|
"get": {
|
|
"operationId": "listWorkOrders",
|
|
"summary": "List work orders (unordered, paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of work orders.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkOrder"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/work-orders/{workOrderId}": {
|
|
"get": {
|
|
"operationId": "getWorkOrder",
|
|
"summary": "Get one work order",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkOrderId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The work order.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrder"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"x-planned": true,
|
|
"operationId": "patchWorkOrder",
|
|
"summary": "PLANNED (phase 2): update dispatch fields on a work order",
|
|
"description": "Not implemented - returns 501. Phase-2 write-back for SHOC dispatch workflow (status/assignment). Writes will stamp `write_origin: shoc-write-api` so the outbound webhook never echoes SHOC's own writes back at it. Ships with its own IAM diff and cross-family review.",
|
|
"responses": {
|
|
"501": {
|
|
"$ref": "#/components/responses/NotImplemented"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/work-orders/{workOrderId}/comments": {
|
|
"get": {
|
|
"operationId": "listWorkOrderComments",
|
|
"summary": "List comments/events for a work order (paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkOrderId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of comments (all source-email event records: comments, updates, cancellations).",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkOrderComment"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"x-planned": true,
|
|
"operationId": "createWorkOrderComment",
|
|
"summary": "PLANNED (phase 2): append a SHOC-authored comment",
|
|
"description": "Not implemented - returns 501. Phase-2 write-back: SHOC dispatch notes land in WorkOrderComments with `write_origin: shoc-write-api` (append-only; no field conflicts with the email pipeline). Ships with its own IAM diff and cross-family review.",
|
|
"responses": {
|
|
"501": {
|
|
"$ref": "#/components/responses/NotImplemented"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/purchase-orders": {
|
|
"get": {
|
|
"operationId": "listPurchaseOrders",
|
|
"summary": "List purchase orders (unordered, paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of purchase orders.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PurchaseOrder"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/purchase-orders/{poNumber}": {
|
|
"get": {
|
|
"operationId": "getPurchaseOrder",
|
|
"summary": "Get one purchase order",
|
|
"parameters": [
|
|
{
|
|
"name": "poNumber",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Coupa PO number, e.g. `2D-22030794`."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The purchase order.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PurchaseOrder"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/verified-sites": {
|
|
"get": {
|
|
"operationId": "listVerifiedSites",
|
|
"summary": "List verified Amazon sites (unordered, paginated)",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/Limit"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/Cursor"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "One page of verified sites.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["items", "next_cursor"],
|
|
"properties": {
|
|
"items": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/VerifiedSite"
|
|
}
|
|
},
|
|
"next_cursor": {
|
|
"$ref": "#/components/schemas/NextCursor"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/verified-sites/{siteCode}": {
|
|
"get": {
|
|
"operationId": "getVerifiedSite",
|
|
"summary": "Get one verified site",
|
|
"parameters": [
|
|
{
|
|
"name": "siteCode",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Amazon site code, e.g. `JFK8`."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The verified site.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/VerifiedSite"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/docs": {
|
|
"get": {
|
|
"operationId": "getDocs",
|
|
"summary": "This documentation page (token-gated)",
|
|
"security": [
|
|
{
|
|
"docsToken": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "token",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Browser convenience: the docs token as a query parameter (browsers can't set headers on navigation). Prefer the X-Auth-Token header from tooling."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Self-contained HTML reference page.",
|
|
"content": {
|
|
"text/html": {}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/openapi.json": {
|
|
"get": {
|
|
"operationId": "getOpenApiSpec",
|
|
"summary": "This spec (token-gated)",
|
|
"security": [
|
|
{
|
|
"docsToken": []
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The OpenAPI 3.1 document.",
|
|
"content": {
|
|
"application/json": {}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"webhooks": {
|
|
"work_order.created": {
|
|
"post": {
|
|
"summary": "Outbound: a work order was created",
|
|
"description": "Sent by `workorder-shoc-emitter` (seahaven-prod) to the configured SHOC endpoint. Full contract incl. HMAC verification, ordering, and retry semantics: `docs/shoc-webhook-contract.md` (Rev 2026-07-23). Requests carry `X-SH-Timestamp`, `X-SH-Key-Id`, and `X-SH-Signature: v1=hex(HMAC_SHA256(secret, \"{timestamp}.{raw_body}\"))`; verify over the raw body, constant-time, +/-300s window, fail closed.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrderEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered. Respond fast (<10s); accept-and-enqueue if processing is slow. 429/5xx/timeouts are retried in order for 24h; other 4xx park immediately."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"work_order.updated": {
|
|
"post": {
|
|
"summary": "Outbound: a work order changed",
|
|
"description": "Same envelope and semantics as work_order.created; `data` is the full current state, not a diff.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrderEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"work_order.cancelled": {
|
|
"post": {
|
|
"summary": "Outbound: a work order transitioned to cancelled",
|
|
"description": "A specialization of work_order.updated (same body) emitted when `wo_status` transitions to `cancelled`.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/WorkOrderEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"work_order.comment_added": {
|
|
"post": {
|
|
"summary": "Outbound: a comment/event record was ingested",
|
|
"description": "One per source email (comments, updates, and cancellation event records). Dedupe on `delivery_id` or `data.comment_id`. May occasionally arrive before the work order's created event - upsert a skeleton work order and let the state event backfill it.",
|
|
"requestBody": {
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CommentEventEnvelope"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"2XX": {
|
|
"description": "Delivered."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"sigv4": {
|
|
"type": "apiKey",
|
|
"name": "Authorization",
|
|
"in": "header",
|
|
"x-amazon-apigateway-authtype": "awsSigv4",
|
|
"description": "AWS IAM SigV4 (service execute-api, region us-east-1). Cross-account callers must be allowed by the API resource policy; Postman signs natively via Authorization type 'AWS Signature'."
|
|
},
|
|
"docsToken": {
|
|
"type": "apiKey",
|
|
"name": "X-Auth-Token",
|
|
"in": "header",
|
|
"description": "Shared docs token (secret procurement-ingest/web-ui-auth-token). Docs routes only."
|
|
}
|
|
},
|
|
"parameters": {
|
|
"Limit": {
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 500,
|
|
"default": 100
|
|
},
|
|
"description": "Page size; values outside 1-500 are clamped."
|
|
},
|
|
"Cursor": {
|
|
"name": "cursor",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Opaque pagination cursor from the previous page's `next_cursor`. Malformed cursors return 400."
|
|
},
|
|
"WorkOrderId": {
|
|
"name": "workOrderId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"description": "Numeric APM work-order id, e.g. `11144580730`."
|
|
}
|
|
},
|
|
"responses": {
|
|
"BadRequest": {
|
|
"description": "Malformed cursor or limit.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Unauthorized": {
|
|
"description": "Missing or wrong docs token.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Forbidden": {
|
|
"description": "SigV4 auth failed or the caller is not allowed by the API resource policy (returned by API Gateway, not the Lambda)."
|
|
},
|
|
"NotFound": {
|
|
"description": "No record with that id.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"NotImplemented": {
|
|
"description": "Planned phase-2 endpoint; not implemented yet.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"schemas": {
|
|
"Error": {
|
|
"type": "object",
|
|
"required": ["error"],
|
|
"properties": {
|
|
"error": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"NextCursor": {
|
|
"type": ["string", "null"],
|
|
"description": "Pass as `cursor` to fetch the next page; `null` means this is the last page."
|
|
},
|
|
"WorkOrder": {
|
|
"type": "object",
|
|
"description": "Mirrors the WorkOrders DynamoDB item (PK work_order_id). Fields absent from the source email are absent or null.",
|
|
"required": ["work_order_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"wo_status": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new", "assigned", "in_progress", "on_hold", "completed", "cancelled", "unknown", null],
|
|
"description": "`unknown` is a real emitted value - map it explicitly."
|
|
},
|
|
"description": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"customer": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"site_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"building": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"severity": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"priority": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"assigned_to": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"date_reported": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"scheduled_start": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"due_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new_work_order", "update", "comment", "cancellation", null],
|
|
"description": "Type of the most recent source email."
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"],
|
|
"description": "ISO 8601 with UTC offset."
|
|
},
|
|
"updated_at": {
|
|
"type": ["string", "null"],
|
|
"description": "ISO 8601 with UTC offset."
|
|
},
|
|
"source_email_s3_key": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"WorkOrderComment": {
|
|
"type": "object",
|
|
"description": "Mirrors the WorkOrderComments DynamoDB item (PK work_order_id, SK comment_id). One row per source email event.",
|
|
"required": ["work_order_id", "comment_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string"
|
|
},
|
|
"comment_id": {
|
|
"type": "string",
|
|
"description": "`{work_order_id}#{time|nocomment}#{sha256(s3_key)[:12]}` - unique per source email, stable across retries; a dedupe key."
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new_work_order", "update", "comment", "cancellation", null]
|
|
},
|
|
"commenter": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"text": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"],
|
|
"description": "Display timestamp (comment time when the source email carried one)."
|
|
},
|
|
"ingested_at": {
|
|
"type": ["string", "null"],
|
|
"description": "When the pipeline wrote the row; ISO 8601 with UTC offset."
|
|
},
|
|
"source_email_s3_key": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"PurchaseOrder": {
|
|
"type": "object",
|
|
"description": "Mirrors the purchase-orders DynamoDB item (PK po_number). Shape follows the Coupa extraction schema; older records may lack newer fields.",
|
|
"required": ["po_number"],
|
|
"properties": {
|
|
"po_number": {
|
|
"type": "string"
|
|
},
|
|
"po_status": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"email_type": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"source_system": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"submitted_by": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"on_behalf_of": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"order_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"revision_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"payment_terms": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"requisition_number": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"department": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"view_order_url": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"supplier": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"name": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"site_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"ship_to": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"name": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"street": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"city": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"state": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"zip": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"location_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"attn": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"total_amount": {
|
|
"type": ["number", "null"],
|
|
"description": "Stored as Decimal; serialized as a JSON number."
|
|
},
|
|
"currency": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"fiscal_year": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"trade": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"coupa_category": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"line_items": {
|
|
"type": ["array", "null"],
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"description": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"quantity": {
|
|
"type": ["number", "null"]
|
|
},
|
|
"unit": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"price": {
|
|
"type": ["number", "null"]
|
|
},
|
|
"amount": {
|
|
"type": ["number", "null"]
|
|
},
|
|
"currency": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"need_by": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"category": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"account_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"period": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
}
|
|
},
|
|
"cancelled_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"processed_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"raw_s3_key": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"data_source": {
|
|
"type": ["string", "null"]
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"VerifiedSite": {
|
|
"type": "object",
|
|
"description": "Mirrors the verified-sites DynamoDB item (PK siteCode), maintained by the PO site extractor.",
|
|
"required": ["siteCode"],
|
|
"properties": {
|
|
"siteCode": {
|
|
"type": "string"
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"city": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"state": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"zip": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"fullAddress": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"locationCode": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"poCount": {
|
|
"type": ["integer", "null"],
|
|
"description": "Count of POs that referenced this site."
|
|
},
|
|
"sourcePOs": {
|
|
"type": ["array", "null"],
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "PO numbers that referenced this site (string set; serialized sorted)."
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
},
|
|
"WebhookEnvelope": {
|
|
"type": "object",
|
|
"description": "Common webhook envelope (contract section 3). Headers: X-SH-Timestamp (unix seconds), X-SH-Key-Id, X-SH-Signature (v1=hex HMAC-SHA256 over '{timestamp}.{raw_body}').",
|
|
"required": ["schema_version", "delivery_id", "event_type", "occurred_at", "source", "replay", "data"],
|
|
"properties": {
|
|
"schema_version": {
|
|
"type": "integer",
|
|
"description": "Reject versions you don't know."
|
|
},
|
|
"delivery_id": {
|
|
"type": "string",
|
|
"description": "Unique per source event, stable across producer retries - the idempotency key."
|
|
},
|
|
"event_type": {
|
|
"type": "string",
|
|
"enum": ["work_order.created", "work_order.updated", "work_order.cancelled", "work_order.comment_added"]
|
|
},
|
|
"occurred_at": {
|
|
"type": "string",
|
|
"description": "ISO 8601 with UTC offset."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"const": "procurement-ingest/workorder-shoc-emitter"
|
|
},
|
|
"replay": {
|
|
"type": "boolean",
|
|
"description": "true when re-sent by the operator replay tool; same idempotency rules."
|
|
},
|
|
"data": {
|
|
"type": "object"
|
|
}
|
|
}
|
|
},
|
|
"WorkOrderEventEnvelope": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/WebhookEnvelope"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/WorkOrderEventData"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"CommentEventEnvelope": {
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/WebhookEnvelope"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"$ref": "#/components/schemas/CommentEventData"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"WorkOrderEventData": {
|
|
"type": "object",
|
|
"description": "Full current work-order state (not a diff); contract section 4.1. Same fields as WorkOrder minus source_email_s3_key.",
|
|
"required": ["work_order_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"wo_status": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new", "assigned", "in_progress", "on_hold", "completed", "cancelled", "unknown", null]
|
|
},
|
|
"description": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"customer": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"site_code": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"building": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"address": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"severity": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"priority": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"assigned_to": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"date_reported": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"scheduled_start": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"due_date": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"],
|
|
"enum": ["new_work_order", "update", "comment", "cancellation", null]
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"updated_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"write_origin": {
|
|
"type": ["string", "null"],
|
|
"description": "Forward-compat (phase 2): present on records written through the write-back API; the emitter skips those, so receivers should tolerate but never see it."
|
|
}
|
|
}
|
|
},
|
|
"CommentEventData": {
|
|
"type": "object",
|
|
"description": "Contract section 4.2. Same fields as WorkOrderComment minus source_email_s3_key.",
|
|
"required": ["work_order_id", "comment_id"],
|
|
"properties": {
|
|
"work_order_id": {
|
|
"type": "string"
|
|
},
|
|
"comment_id": {
|
|
"type": "string"
|
|
},
|
|
"record_type": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"commenter": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"text": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"created_at": {
|
|
"type": ["string", "null"]
|
|
},
|
|
"ingested_at": {
|
|
"type": ["string", "null"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|