@ultracart/bq-skill 0.1.2

package/schemas/report-manifest.schema.json

@@ -0,0 +1,309 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ultracart.com/schemas/report-manifest.schema.json",
+  "title": "UltraCart BigQuery Report Manifest",
+  "description": "A replayable report definition that captures the full report pipeline: question, parameters, SQL, chart config, and run history.",
+  "type": "object",
+  "required": ["name", "description", "created", "last_run", "prompt", "config", "sql_file", "chart"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable report name",
+      "minLength": 1,
+      "maxLength": 100
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of what the report shows",
+      "maxLength": 500
+    },
+    "created": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO 8601 date when the report was first created"
+    },
+    "last_run": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO 8601 date when the report was last executed"
+    },
+    "prompt": {
+      "type": "string",
+      "description": "The original natural language question that created this report"
+    },
+    "refinements": {
+      "type": "array",
+      "description": "Ordered list of refinement instructions applied after initial creation",
+      "items": {
+        "type": "string"
+      }
+    },
+
+    "parameters": {
+      "type": "array",
+      "description": "Parameter definitions required to run this report",
+      "items": {
+        "$ref": "#/$defs/parameter"
+      }
+    },
+
+    "run_history": {
+      "type": "array",
+      "description": "Log of past executions with resolved parameter values",
+      "items": {
+        "$ref": "#/$defs/run_history_entry"
+      }
+    },
+
+    "config": {
+      "type": "object",
+      "description": "BigQuery configuration snapshot from when the report was created",
+      "required": ["merchant_id", "project_id", "taxonomy_level", "dataset", "tables_used"],
+      "additionalProperties": false,
+      "properties": {
+        "merchant_id": {
+          "type": "string"
+        },
+        "project_id": {
+          "type": "string"
+        },
+        "taxonomy_level": {
+          "type": "string",
+          "enum": ["standard", "low", "medium", "high"]
+        },
+        "dataset": {
+          "type": "string"
+        },
+        "tables_used": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        }
+      }
+    },
+
+    "sql_file": {
+      "type": "string",
+      "description": "Relative path to the SQL template file with {{parameter}} placeholders",
+      "pattern": "\\.sql$"
+    },
+
+    "chart": {
+      "type": "object",
+      "description": "Visualization configuration",
+      "required": ["type", "echarts_file", "output_format", "width", "height"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["bar", "line", "area", "stacked-bar", "stacked-area", "pie", "donut", "scatter", "heatmap", "treemap", "funnel", "gauge", "radar", "candlestick", "boxplot"],
+          "description": "The ECharts visualization type"
+        },
+        "echarts_file": {
+          "type": "string",
+          "description": "Relative path to the battle-hardened ECharts JavaScript file",
+          "pattern": "\\.js$"
+        },
+        "output_format": {
+          "type": "string",
+          "enum": ["png", "pdf", "both"]
+        },
+        "width": {
+          "type": "integer",
+          "minimum": 400,
+          "maximum": 3840
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 300,
+          "maximum": 2160
+        }
+      }
+    },
+
+    "analysis": {
+      "type": "object",
+      "description": "Executive analysis settings",
+      "additionalProperties": false,
+      "properties": {
+        "include": {
+          "type": "boolean",
+          "description": "Whether to generate an executive analysis on each run",
+          "default": true
+        },
+        "prompt_file": {
+          "type": "string",
+          "description": "Relative path to the analysis system prompt template (generated at design time, used at replay time by a separate LLM call to produce fresh analysis)",
+          "pattern": "\\.md$",
+          "default": "analysis_prompt.md"
+        },
+        "output_file": {
+          "type": "string",
+          "description": "Relative path for the analysis markdown file",
+          "pattern": "\\.md$",
+          "default": "report.md"
+        }
+      }
+    },
+
+    "delivery": {
+      "type": "object",
+      "description": "Report delivery configuration for Slack and/or email",
+      "properties": {
+        "slack": {
+          "type": "object",
+          "properties": {
+            "channels": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "description": "Slack channel IDs (e.g., C0123456789)"
+            }
+          },
+          "required": ["channels"],
+          "additionalProperties": false
+        },
+        "email": {
+          "type": "object",
+          "properties": {
+            "to": {
+              "type": "array",
+              "items": { "type": "string", "format": "email" },
+              "minItems": 1,
+              "description": "Recipient email addresses"
+            },
+            "subject": {
+              "type": "string",
+              "description": "Email subject line"
+            },
+            "provider": {
+              "type": "string",
+              "enum": ["sendgrid", "ses", "postmark", "mailgun", "resend"],
+              "description": "Email delivery provider"
+            }
+          },
+          "required": ["to", "subject", "provider"],
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+
+  "$defs": {
+    "parameter": {
+      "type": "object",
+      "description": "A single report parameter definition",
+      "required": ["name", "type", "label", "description", "required"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Parameter identifier used in SQL placeholders (e.g., {{name}})",
+          "pattern": "^[a-z][a-z0-9_]*$"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["date", "string", "number", "boolean", "enum"],
+          "description": "The parameter data type. Determines validation rules and prompt behavior."
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label shown when prompting the user",
+          "maxLength": 50
+        },
+        "description": {
+          "type": "string",
+          "description": "Help text explaining what this parameter controls",
+          "maxLength": 200
+        },
+        "required": {
+          "type": "boolean",
+          "description": "If true, the parameter must be resolved before the report can run"
+        },
+        "default": {
+          "description": "Default value. For date types, supports relative expressions: 'today', '-Nd' (N days ago), '-Nw' (N weeks ago), '-Nm' (N months ago), 'start_of_month', 'start_of_quarter', 'start_of_year'",
+          "oneOf": [
+            { "type": "string" },
+            { "type": "number" },
+            { "type": "boolean" }
+          ]
+        },
+        "options": {
+          "type": "array",
+          "description": "Valid values for enum-type parameters. Ignored for other types.",
+          "items": { "type": "string" },
+          "minItems": 2
+        },
+        "validation": {
+          "type": "object",
+          "description": "Optional validation constraints beyond type checking",
+          "properties": {
+            "min": {
+              "type": "number",
+              "description": "Minimum value for number-type parameters"
+            },
+            "max": {
+              "type": "number",
+              "description": "Maximum value for number-type parameters"
+            },
+            "pattern": {
+              "type": "string",
+              "description": "Regex pattern for string-type parameters"
+            },
+            "min_date": {
+              "type": "string",
+              "description": "Earliest allowed date (ISO 8601 or relative expression)"
+            },
+            "max_date": {
+              "type": "string",
+              "description": "Latest allowed date (ISO 8601 or relative expression)"
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+
+    "run_history_entry": {
+      "type": "object",
+      "description": "A record of a single report execution",
+      "required": ["run_date", "parameters"],
+      "additionalProperties": false,
+      "properties": {
+        "run_date": {
+          "type": "string",
+          "format": "date",
+          "description": "The date this run was executed"
+        },
+        "parameters": {
+          "type": "object",
+          "description": "The resolved parameter values used for this run. Keys are parameter names, values are the resolved (not relative) values.",
+          "additionalProperties": true
+        },
+        "status": {
+          "type": "string",
+          "enum": ["success", "error"],
+          "description": "Whether the run completed successfully"
+        },
+        "error_message": {
+          "type": "string",
+          "description": "Error details if status is 'error'"
+        },
+        "rows_returned": {
+          "type": "integer",
+          "description": "Number of rows returned by the query",
+          "minimum": 0
+        },
+        "bytes_processed": {
+          "type": "integer",
+          "description": "Bytes processed by BigQuery (for cost tracking)",
+          "minimum": 0
+        }
+      }
+    }
+  }
+}

package/schemas/tables/README.md

@@ -0,0 +1,45 @@
+# Enhanced Table Schemas
+
+This directory contains enhanced BigQuery table schemas with human-readable descriptions and `allowed_values` arrays generated from UltraCart's REST objects.
+
+## Structure
+
+```
+tables/
+├── ultracart_dw/              # Standard taxonomy dataset (no PII columns)
+├── ultracart_dw_low/          # Low taxonomy dataset
+├── ultracart_dw_medium/       # Medium taxonomy dataset (includes PII columns)
+├── ultracart_dw_high/         # High taxonomy dataset (full access)
+└── ultracart_dw_streaming/    # Streaming dataset (analytics, screen recordings)
+```
+
+Each subdirectory corresponds to a BigQuery dataset and taxonomy level. The schema files are organized by dataset so taxonomy-level restrictions are respected — a standard-taxonomy user never sees PII columns.
+
+## File Format
+
+Each file is a JSON array matching the BigQuery schema structure with additional fields:
+
+```json
+[
+  {
+    "name": "column_name",
+    "type": "STRING",
+    "mode": "NULLABLE",
+    "description": "Human-readable description of what this column contains",
+    "allowed_values": ["value1", "value2", "value3"],
+    "mandatory": true
+  }
+]
+```
+
+- `description` — Helps the LLM understand the column's business meaning
+- `allowed_values` — Constrains the LLM to valid values when writing SQL filters
+- `mandatory` — If true, this column is always included in schema filtering
+
+## Resolution Priority
+
+When the CLI needs a table schema:
+1. Check for an enhanced schema file here (`tables/{dataset}/{table}.json`)
+2. Fall back to live BigQuery metadata if no enhanced schema exists
+
+Use `uc-bq schema --tables=TABLE --live` to bypass enhanced schemas and fetch directly from BigQuery.

package/schemas/tables/ultracart_dw/uc_affiliate_clicks.json

@@ -0,0 +1,186 @@
+[
+  {
+    "mode": "NULLABLE",
+    "name": "partition_date",
+    "type": "DATE"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "affiliate_click_oid",
+    "description": "Unique object identifier for this click",
+    "type": "INTEGER"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "affiliate_oid",
+    "description": "Affiliate object ID associated with this click",
+    "type": "INTEGER"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "click_dts",
+    "description": "Date/time that the click was made",
+    "type": "DATETIME"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "ip_address",
+    "description": "IP address that generated the click",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "referrer",
+    "description": "URL that referred the click (Browser Header Referer)",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "sub_id",
+    "description": "Sub ID value passed on the click",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "affiliate_link_oid",
+    "description": "Unique object identifier for for the link that this click is associated with",
+    "type": "INTEGER"
+  },
+  {
+    "name": "link",
+    "description": "Link object associated with this click",
+    "type": "RECORD",
+    "fields": [
+      {
+        "mode": "NULLABLE",
+        "name": "affiliate_link_oid",
+        "description": "Unique object identifier associated with this link",
+        "type": "INTEGER"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "affiliate_oid",
+        "description": "Affiliate object ID associated with this link",
+        "type": "INTEGER"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "creative_oid",
+        "description": "Creative (image or text) associated with this link",
+        "type": "INTEGER"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "custom_html",
+        "description": "Custom HTML associated with this link",
+        "type": "STRING"
+      },
+      {
+        "allowed_values": [
+          "Pending",
+          "Approved",
+          "Rejected"
+        ],
+        "mode": "NULLABLE",
+        "name": "custom_html_approval_status",
+        "description": "Approved status of the custom html",
+        "type": "STRING"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "invisible_link_url_prefix",
+        "description": "Invisible link URL prefix",
+        "type": "STRING"
+      },
+      {
+        "allowed_values": [
+          "Pending",
+          "Approved",
+          "Rejected"
+        ],
+        "mode": "NULLABLE",
+        "name": "invisible_link_approval_status",
+        "description": "Invisible link approval status",
+        "type": "STRING"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "deleted",
+        "description": "True if the link has been deleted",
+        "type": "BOOLEAN"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "name",
+        "description": "Name of the link",
+        "type": "STRING"
+      },
+      {
+        "allowed_values": [
+          "image",
+          "text",
+          "invisible",
+          "direct"
+        ],
+        "mode": "NULLABLE",
+        "name": "type",
+        "description": "Type of link",
+        "type": "STRING"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "custom_landing_url",
+        "description": "Custom landing page URL if configured",
+        "type": "STRING"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "code",
+        "description": "Code associated with the link",
+        "type": "STRING"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "affiliate_program_item_oid",
+        "description": "The affiliate program item this managed link is associated with",
+        "type": "INTEGER"
+      },
+      {
+        "mode": "NULLABLE",
+        "name": "affiliate_managed_link_oid",
+        "description": "Managed link OID that this link object was generated from",
+        "type": "INTEGER"
+      }
+    ]
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "referrer_query_string",
+    "description": "Query string that was on the referrer URL.",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "landing_page",
+    "description": "URL of the landing page the customer was sent to.",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "landing_page_query_string",
+    "description": "Query string on the landing page URL the customer was sent to.",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "ucacid",
+    "description": "UC Analytics Identifier",
+    "type": "STRING"
+  },
+  {
+    "mode": "NULLABLE",
+    "name": "screen_recording_uuid",
+    "description": "Screen recording UUID",
+    "type": "STRING"
+  }
+]