mirror of
https://github.com/Sea-Haven-Industries/procurement-ingest.git
synced 2026-09-30 20:03:14 +00:00
b89e98a879
Some checks are pending
Deploy / deploy (push) Waiting to run
* feat(api): Add @redocly/cli as a dev dependency
Signed-off-by: Adam Moussa <adam@seahavenind.com>
* feat(api): Add Redocly configuration file with custom rules
Signed-off-by: Adam Moussa <adam@seahavenind.com>
* chore(api): Redocly lint config + bring openapi.json into compliance
redocly.yaml from the Redocly guidelines builder, with three generated
rules corrected: response-contains-property had the status codes as the
required body fields (intent was the Error schema's top-level 'error';
403 exempt since API Gateway emits AWS's {message} shape, 501 not 503);
operation-4xx-problem-details-rfc7807 off (adopting RFC 7807 would be a
runtime + SHOC-contract change, decided against); the two inert casing
rules (parameter names, schema properties) removed because both name
sets are contract-pinned (gateway resource paths, DynamoDB items).
Spec changes, no runtime impact: operationIds renamed to method-prefixed
kebab-case (get-work-orders, post-work-order-comment, ...); tags added to
all 15 operations + root tags object (groups the Redoc sidebar); examples
on all six parameters; license field; server description punctuation; two
descriptions reworded to start capitalized. Real linter catches fixed:
the two x-planned ops were missing their {workOrderId} path parameter
and any 4xx response (403 added - true today, gateway rejects unsigned).
.redocly.lint-ignore.yaml pins the six deliberate exceptions: webhook
keys are the shipped SHOC contract event names (not renameable), and the
x-planned ops answer only 501 (no 2xx to document).
package.json: npm run lint:api. Verified: lint 0 errors, 675 pytest,
headless-Chrome render of the tagged docs page.
* feat(api): SHOC design-system theme for /docs (vendored fonts)
Themes the Redoc page with the canonical SHOC token set: Montserrat 600
headings / DM Sans body / JetBrains Mono code, primary #1c75bc, navy
#262262 sidebar text + right panel, #f9fafb background, 244px sidebar.
sortRequiredPropsFirst on; 200 responses pre-expanded.
Fonts ship as lambdas/api/fonts.css (latin woff2 subsets from
@fontsource 5.3.0, embedded as data URIs, ~90KB) and inline via a new
__FONTS_CSS__ placeholder with the same </style breakout guard --
the offline single-response invariant holds, nothing fetches Google
Fonts (test-pinned). Bundling cp + bundle-consistency pin + spec-drift
asset checks extended.
Verified: headless-Chrome render (theme + fonts applied), ruff, 675
pytest, cdk synth + staged-asset check.
* feat(api): SHOC gradient topbar on /docs
64px fixed header with the SHOC shell gradient token (#1b1f52 ->
#1c4f8f -> #1c75bc), Sea Haven wordmark in Montserrat 600, page name
right-aligned in DM Sans. Redoc's scrollYOffset: 64 keeps the sticky
sidebar and anchor scrolling clear of the fixed bar. Verified via
headless-Chrome render.
* style(api): normalize /docs header and right-panel blues
The right panel's #262262 is a purple-leaning navy that clashed with
the cyan-leaning gradient, and the bar's brightest point sat directly
over the dark panel. Right panel now uses #1b1f52 (the gradient's own
dark endpoint) and the gradient runs bright-to-dark so its dark end
lands flush on the panel -- no seam, one blue family. Verified via
headless-Chrome render.
* style(api): right-panel gradient on /docs via bundle-pinned override
Redoc's theme only takes solid colors (it derives shades from
rightPanel.backgroundColor), so the gradient (#1b3d79 -> #1b3068 ->
#1b1f52, continuing the topbar blend) rides as a CSS override on the
styled-components classes of the per-section right-panel divs
(.sc-iGgWBj.sc-gsFSXq + the .sc-dExYaf stub). Those names are
deterministic for the vendored 2.5.3 bundle (verified across loads) but
change on any Redoc bump: re-derive via headless probe (find elements
whose computed background equals the rightPanel color). If they stop
matching, the panel falls back to the solid #1b1f52 theme color --
cosmetic only. Verified via headless-Chrome render.
* feat(api): collapsible samples column on /docs
Redoc CE has no built-in panel toggle, so the topbar gains a Hide/Show
samples button that flips .samples-collapsed on <html>: the right-panel
divs hide (same bundle-pinned styled-components classes as the gradient
override) and each section's content half takes the full width. Choice
persists in localStorage; aria-pressed tracks state. If the pinned
classes stop matching after a Redoc bump the toggle goes inert --
cosmetic only. Both states verified via headless-Chrome render.
* ci(api): spec-lint CI gate + npm Dependabot coverage
New spec-lint job mirrors the local npm run lint:api so openapi.json
cannot drift from redocly.yaml with green CI. Dependabot gains the npm
ecosystem (package.json is new; nothing watched @redocly/cli).
* feat(api): docs finishing touches - x-tagGroups, favicon, docs:preview
x-tagGroups sections the Redoc sidebar (Read API / Meta / SHOC Feed);
inline data-URI SVG favicon (SHOC blue) stops the browser's follow-up
/favicon.ico request 403ing at the gateway; npm run docs:preview wraps
the real-handler local render (scripts/preview_docs.py); README gains a
docs-page architecture section covering the inline pattern, theme,
pinned-selector caveat, and tooling. Lint 0 errors, 675 pytest,
headless render verified.
---------
Signed-off-by: Adam Moussa <adam@seahavenind.com>
1097 lines
33 KiB
JSON
1097 lines
33 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Procurement Ingest API",
|
|
"version": "1.0.0",
|
|
"license": {
|
|
"name": "Proprietary (Sea Haven Industries, internal)"
|
|
},
|
|
"description": "Read API over the procurement-ingest pipelines (work orders and purchase orders). The outbound SHOC work-order webhook feed is documented under **webhooks** below.\n\nData endpoints use AWS IAM SigV4; the `/docs` and `/openapi.json` routes use a shared token. Listings are unordered, cursor-paginated scans. Endpoints tagged **x-planned** are phase 2 and currently answer `501`.\n\nThis API replaces SHOC's retired SyncController DynamoDB scan as the reconciliation and backfill path. Full detail: the repo README and `docs/shoc-webhook-contract.md`."
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://mvul1efda2.execute-api.us-east-1.amazonaws.com/prod",
|
|
"description": "seahaven-prod (011934824531)."
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"sigv4": []
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "Work Orders",
|
|
"description": "Work orders ingested from APM emails (WorkOrders and WorkOrderComments tables)."
|
|
},
|
|
{
|
|
"name": "Purchase Orders",
|
|
"description": "Coupa purchase orders ingested from PO emails (purchase-orders table)."
|
|
},
|
|
{
|
|
"name": "Verified Sites",
|
|
"description": "Amazon site directory maintained by the PO site extractor (verified-sites table)."
|
|
},
|
|
{
|
|
"name": "Docs",
|
|
"description": "This documentation page and the raw OpenAPI document (token-gated)."
|
|
},
|
|
{
|
|
"name": "Outbound Webhooks",
|
|
"description": "Events pushed by workorder-shoc-emitter to the configured SHOC endpoint."
|
|
}
|
|
],
|
|
"x-tagGroups": [
|
|
{
|
|
"name": "Read API",
|
|
"tags": ["Work Orders", "Purchase Orders", "Verified Sites"]
|
|
},
|
|
{
|
|
"name": "Meta",
|
|
"tags": ["Docs"]
|
|
},
|
|
{
|
|
"name": "SHOC Feed",
|
|
"tags": ["Outbound Webhooks"]
|
|
}
|
|
],
|
|
"paths": {
|
|
"/work-orders": {
|
|
"get": {
|
|
"operationId": "get-work-orders",
|
|
"tags": ["Work Orders"],
|
|
"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": "get-work-order",
|
|
"tags": ["Work Orders"],
|
|
"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": "patch-work-order",
|
|
"tags": ["Work Orders"],
|
|
"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.",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkOrderId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"501": {
|
|
"$ref": "#/components/responses/NotImplemented"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/work-orders/{workOrderId}/comments": {
|
|
"get": {
|
|
"operationId": "get-work-order-comments",
|
|
"tags": ["Work Orders"],
|
|
"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": "post-work-order-comment",
|
|
"tags": ["Work Orders"],
|
|
"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.",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkOrderId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"501": {
|
|
"$ref": "#/components/responses/NotImplemented"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/purchase-orders": {
|
|
"get": {
|
|
"operationId": "get-purchase-orders",
|
|
"tags": ["Purchase Orders"],
|
|
"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": "get-purchase-order",
|
|
"tags": ["Purchase Orders"],
|
|
"summary": "Get one purchase order",
|
|
"parameters": [
|
|
{
|
|
"name": "poNumber",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Coupa PO number, e.g. `2D-22030794`.",
|
|
"example": "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": "get-verified-sites",
|
|
"tags": ["Verified Sites"],
|
|
"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": "get-verified-site",
|
|
"tags": ["Verified Sites"],
|
|
"summary": "Get one verified site",
|
|
"parameters": [
|
|
{
|
|
"name": "siteCode",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Amazon site code, e.g. `JFK8`.",
|
|
"example": "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": "get-docs",
|
|
"tags": ["Docs"],
|
|
"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.",
|
|
"example": "your-docs-token"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Self-contained HTML reference page.",
|
|
"content": {
|
|
"text/html": {}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/openapi.json": {
|
|
"get": {
|
|
"operationId": "get-openapi-spec",
|
|
"tags": ["Docs"],
|
|
"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": {
|
|
"operationId": "post-work-order-created",
|
|
"tags": ["Outbound Webhooks"],
|
|
"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": {
|
|
"operationId": "post-work-order-updated",
|
|
"tags": ["Outbound Webhooks"],
|
|
"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": {
|
|
"operationId": "post-work-order-cancelled",
|
|
"tags": ["Outbound Webhooks"],
|
|
"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": {
|
|
"operationId": "post-work-order-comment-added",
|
|
"tags": ["Outbound Webhooks"],
|
|
"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.",
|
|
"example": 100
|
|
},
|
|
"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.",
|
|
"example": "eyJ3b3JrX29yZGVyX2lkIjogIjExMTQ0NTgwNzMwIn0"
|
|
},
|
|
"WorkOrderId": {
|
|
"name": "workOrderId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+$"
|
|
},
|
|
"description": "Numeric APM work-order id, e.g. `11144580730`.",
|
|
"example": "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": "The `unknown` value is genuinely emitted - 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": "Format: `{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"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|