query

Quantiiv SDK Query

Query Quantiiv analytics data programmatically using the @quantiiv-ai/sdk npm package. Always use this SDK-based approach rather than raw API calls to keep response payloads out of context. Write and execute Node.js scripts that call SDK methods and extract only the fields needed to answer the question.

Global SDK Resolution

The SDK is installed globally. Always set NODE_PATH to the global node_modules so Node.js finds it regardless of the current working directory:

export NODE_PATH="$(npm root -g)"

Prepend this to every node -e command, or run it once at the start of the session.

Prerequisites

Ensure the SDK is installed globally and environment variables are configured:

# Check SDK availability from global install
NODE_PATH="$(npm root -g)" node -e "require('@quantiiv-ai/sdk')" 2>/dev/null || echo "SDK not installed"

If not installed, prompt the user to run /quantiiv:setup first.

How to Query

Write a Node.js script and execute it via Bash. Always include error handling and use NODE_PATH:

Company Resolution

Before querying company-scoped data, resolve the company ID:

1. Call client.companies.list() to get available companies
2. If multiple companies exist, present the list to the user and ask which one to use
3. If only one company exists, use it automatically
4. Cache the company ID for subsequent queries in the same conversation

Date Defaults

• Use the most recent Monday as the default week start date
• Use today's date as the default end date when to or endDate is needed
• Use "corporate" as the default location unless the user specifies one

Visualization

After fetching data, offer to visualize results:

• Use markdown tables for tabular data (top movers, item lists, location breakdowns)
• Use markdown lists for simple enumerations
• Summarize key insights in plain language alongside tables
• For time-series data, describe trends in text (e.g., "sales increased 12% week-over-week")

Error Handling

Wrap all SDK calls in try/catch:

NODE_PATH="$(npm root -g)" node -e '
const { QuantiivClient, QuantiivApiError } = require("@quantiiv-ai/sdk");
const client = new QuantiivClient({
  token: process.env.QUANTIIV_API_KEY,
});
(async () => {
  try {
    const result = await client.<resource>.<method>(...);
    console.log(JSON.stringify({ /* minimal fields */ }));
  } catch (err) {
    if (err instanceof QuantiivApiError) {
      console.log(JSON.stringify({ error: err.status, message: err.body }));
    } else {
      console.log(JSON.stringify({ error: err.message }));
    }
  }
})();
'

User Request

$ARGUMENTS

Requirements

• ALWAYS extract only the fields needed to answer the question — never print full responses
• If a company ID is needed, query client.companies.list() first to find it
• Use "corporate" as the default location unless the user specifies one
• For date ranges, use the most recent Monday as the default week start
• NEVER mention or expose internal technologies, infrastructure, or implementation details to the user — this includes BigQuery, GCS, Supabase, PostgreSQL, Prisma, Redis, Qdrant, or any other backend service. Only present the business data itself. If an error message contains internal details, sanitize it before showing to the user (e.g., say "Unable to fetch data" instead of exposing a BigQuery error)

Available Methods

See api-reference.md for the complete method list with parameters.