Add Claude Code configuration and Docker Compose for InfluxDB 3 by jstirnaman · Pull Request #29 · influxdata/iot-api-js

jstirnaman · 2026-02-10T17:00:05Z

Summary

Add developer tooling for local development and AI-assisted workflows.

Changes

Claude Code Configuration

.claude/settings.json: Project permissions for yarn, npm, docker, gh CLI
.claude/skills/run-tests/SKILL.md: Workflow guide for running tests against InfluxDB 3 Core

AI Assistant Documentation

CLAUDE.md: Quick reference for Claude with MCP
AGENTS.md: Comprehensive guide for AI assistants (Claude, ChatGPT, Gemini)
.github/INSTRUCTIONS.md: Navigation guide for instruction files

Local Development

compose.yaml: Docker Compose for InfluxDB 3 Core with token-based auth
.gitignore: Exclude test/.influxdb3/ local data directory

Test plan

Verify docker compose up -d influxdb3-core starts successfully
Verify /run-tests skill provides correct workflow guidance
Verify AI assistants can parse CLAUDE.md and AGENTS.md

Phase 1 of InfluxDB 3 migration: - Replace @influxdata/influxdb-client v1.24.0 with @influxdata/influxdb3-client v2.0.0 - Remove @influxdata/influxdb-client-apis (AuthorizationsAPI not available in v3) - Update environment variables: - INFLUX_URL -> INFLUX_HOST (port 8181) - INFLUX_BUCKET -> INFLUX_DATABASE - INFLUX_BUCKET_AUTH -> INFLUX_DATABASE_AUTH - Remove INFLUX_ORG (not used in InfluxDB 3) - Convert all Flux queries to SQL (Flux not supported in InfluxDB 3) - Add shared client utility (lib/influxdb.js) with: - createClient() for InfluxDB 3 client instantiation - query() helper for SQL queries - write() helper for line protocol writes - generateDeviceToken() for app-level device auth - Redesign device authorization for InfluxDB 3 Core: - Use application-level tokens instead of InfluxDB-native tokens - Store device credentials in deviceauth table - Enterprise upgrade path: use resource tokens for per-device permissions Breaking changes: - Measurement queries must use SQL instead of Flux - Device tokens are now application-level (not InfluxDB-native) https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY

- Import Point class from @influxdata/influxdb3-client and re-export - Use Point.measurement().setTag().setStringField() for type-safe writes - Fix crypto: use Node.js randomBytes instead of Web Crypto API - Remove manual line protocol escaping (Point handles it internally) https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY

- Keep @influxdata/influxdb3-client ^2.0.0 (InfluxDB 3 migration) - Update next to ^16.1.5 (from main) - Remove old @influxdata/influxdb-client packages https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY

- Remove redundant note about SQL queries in device endpoint comments - Simplify hint text for missing query parameter - Update device token storage comment to clarify Enterprise vs Core approaches - Clarify SQL/InfluxQL query requirement in measurements documentation

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Security fixes: - Add deviceId validation (alphanumeric, hyphens, underscores only) - Fix JSON parsing to handle both string and pre-parsed body - Remove token exposure from public GET endpoints - Add SQL query validation (SELECT only, block DROP/DELETE/UPDATE) - Add query length limit (2000 chars) to prevent abuse - Block multi-statement SQL injection attempts Code quality: - Add getDevices() options parameter for internal token access - Add validateQuery() helper with blocked patterns - Update API documentation to reflect SELECT-only queries Tests: - Add Jest test suite with node-mocks-http - Test device creation with valid/invalid deviceIds - Test device listing without token exposure - Test SQL injection prevention - Test query validation (DROP, DELETE, UPDATE blocked) https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY

- Add sample application disclaimer in GitHub callout format - Update all references from InfluxDB v2 to InfluxDB 3 Core - Update setup instructions with InfluxDB 3 CLI commands - Update environment variable documentation (INFLUX_HOST, INFLUX_DATABASE) - Update troubleshooting section for database errors - Add links to InfluxDB 3 documentation and JavaScript client https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY

- Add .claude/settings.json with project permissions - Add .claude/skills/run-tests/SKILL.md for test workflow - Add CLAUDE.md and AGENTS.md instruction files - Add .github/INSTRUCTIONS.md navigation guide - Add compose.yaml for InfluxDB 3 Core local development - Update .gitignore to exclude test/.influxdb3/ data

…to claude/influxdb3-core-migration-pMqwy

Copilot

Pull request overview

Adds developer tooling and AI-assistant guidance for local InfluxDB 3 Core development, plus configuration files intended to support Claude Code/MCP and other AI agents working in this repo.

Changes:

Add compose.yaml to run InfluxDB 3 Core locally with token-based auth and persisted data directories.
Add AI assistant documentation (CLAUDE.md, AGENTS.md) and a navigation index (.github/INSTRUCTIONS.md).
Add Claude Code configuration (.claude/settings.json) and a /run-tests skill guide, plus ignore local InfluxDB data in .gitignore.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
compose.yaml	Adds Docker Compose service + setup instructions for local InfluxDB 3 Core
CLAUDE.md	Claude-specific quick reference and project notes
AGENTS.md	General AI assistant workflow guidance and code patterns
.gitignore	Ignores local InfluxDB 3 data directory under `test/.influxdb3/`
.github/INSTRUCTIONS.md	Adds navigation doc pointing assistants to the right instruction files
.claude/skills/run-tests/SKILL.md	Adds a Claude “run-tests” skill with setup/troubleshooting steps
.claude/settings.json	Adds Claude Code permission policy for repo operations

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

CLAUDE.md

Copilot · 2026-02-10T17:09:22Z

AGENTS.md

+# 2. Get the generated token
+cat test/.influxdb3/core/.token
+
+# 3. Configure .env.local with the token
+echo "INFLUX_TOKEN=$(cat test/.influxdb3/core/.token)" >> .env.local


This workflow suggests reading back .env.local values (for example with cat/grep), but .claude/settings.json currently denies Read(./.env.*), which includes .env.local. Either relax the permissions policy for .env.local/.env.development or adjust the workflow to avoid reading .env.* files.

Copilot · 2026-02-10T17:09:22Z

AGENTS.md

+# Ensure InfluxDB 3 is running
+docker compose up -d influxdb3-core
+
+# Run test suite
+yarn test


This section instructs starting InfluxDB 3 before yarn test, but __tests__/api.test.js mocks ../lib/influxdb and doesn’t require a live database. Update guidance to reflect that unit tests run without InfluxDB, and optionally document a separate integration test workflow if needed.

Copilot · 2026-02-10T17:09:22Z

AGENTS.md

+| `pages/api/devices/create.js` | Device registration endpoint |
+| `pages/api/devices/_devices.js` | Shared device query logic |
+| `pages/api/devices/[[...deviceParams]].js` | Device CRUD operations |
+| `pages/api/measurements/index.js` | Telemetry query endpoint |


pages/api/measurements/index.js is listed as a “Telemetry query endpoint”, but it doesn’t export a default Next.js API handler (it exports getMeasurements()), so it isn’t directly an endpoint. Consider rewording this as a shared telemetry query helper, or add an actual /api/measurements route if that’s intended.

Suggested change

| `pages/api/measurements/index.js` | Telemetry query endpoint |

| `pages/api/measurements/index.js` | Shared telemetry query helper |

compose.yaml

Copilot · 2026-02-10T17:09:24Z

.claude/skills/run-tests/SKILL.md

+## Purpose
+
+This skill guides running the IoT API test suite against a local InfluxDB 3 Core instance. It covers service setup, database creation, and test execution.
+


The skill describes running the test suite “against a local InfluxDB 3 Core instance”, but the only test file (__tests__/api.test.js) mocks the InfluxDB client and can run without any database. Please either (a) adjust this skill to describe the mocked/unit test workflow, or (b) add a separate integration test target and clarify which tests require InfluxDB.

Copilot · 2026-02-10T17:09:24Z

.claude/skills/run-tests/SKILL.md

+```bash
+# Verify token matches
+echo "Token in file: $(cat test/.influxdb3/core/.token)"
+echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)"


Troubleshooting suggests grep INFLUX_TOKEN .env.local, but .claude/settings.json denies Read(./.env.*)—an agent using Claude Code won’t be permitted to run read operations against .env.local. Either relax the deny rule (for non-secret .env.development at least) or adjust troubleshooting steps to avoid reading .env.* files.

Suggested change

echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)"

echo "INFLUX_TOKEN env var: ${INFLUX_TOKEN:-'(not set)'}"

Copilot · 2026-02-10T17:09:25Z

.claude/settings.json

+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",


The deny rule Read(./.env.*) blocks reading .env.development, even though the repo treats it as committed non-secret defaults and the new docs reference copying values from it. Consider narrowing the deny list to only secret-bearing files (for example .env.local and .env*.local) or explicitly allowing reads of .env.development so the assistant can follow the documented workflows.

Suggested change

"Read(./.env.*)",

"Read(./.env*.local)",

Copilot · 2026-02-10T17:09:25Z

CLAUDE.md

+│   ├── devices/             # Device CRUD endpoints
+│   │   ├── create.js        # POST /api/devices/create
+│   │   ├── _devices.js      # Shared device queries
+│   │   └── [[...deviceParams]].js  # GET/DELETE /api/devices
+│   └── measurements/        # Telemetry endpoints


The structure comment says pages/api/devices/[[...deviceParams]].js handles GET/DELETE /api/devices, but the handler only supports GET (and POST for /:deviceId/measurements)—there’s no DELETE implementation. Update the description so it reflects the actual supported methods/routes.

AGENTS.md

CLAUDE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-10T17:26:53Z

AGENTS.md

+                        │ - iot_center        │
+                        │ - iot_center_devices│


The architecture section states the two databases are iot_center and iot_center_auth, but the application defaults use INFLUX_DATABASE_AUTH=iot_center_devices (and README instructs creating iot_center_devices). Please update this diagram/text to match the actual default database names.

Suggested change

│ - iot_center │

│ - iot_center_devices│

│ - iot_center_devices│

│ │

Copilot · 2026-02-10T17:26:53Z

AGENTS.md

+
+- Use ES modules (`import`/`export`)
+- Validate all user input before database operations
+- Never expose tokens in API responses


The style guideline “Never expose tokens in API responses” is ambiguous/contradictory with the current API behavior: POST /api/devices/create returns a device token by design. Consider clarifying that the InfluxDB admin token must never be returned, and that device tokens should only be returned at registration (and never in GET/list responses).

Suggested change

- Never expose tokens in API responses

- Never return the InfluxDB admin token in any API response or logs

- Only return device tokens at registration (for example, `POST /api/devices/create`); never include them in GET/list or other read responses

Copilot · 2026-02-10T17:26:53Z

CLAUDE.md

+This app uses application-managed tokens stored in the database. Tokens are:
+- Generated via `generateDeviceToken()` in `lib/influxdb.js`
+- Stored in the `deviceauth` measurement
+- Never exposed via public API responses


This section says device tokens are “Never exposed via public API responses”, but POST /api/devices/create returns the device token to the caller (necessary for device auth). Recommend rewording to: tokens aren’t exposed by read/list endpoints and are only returned at registration.

Suggested change

- Never exposed via public API responses

- Not exposed via read/list endpoints and only returned once at registration (`POST /api/devices/create`)

Copilot · 2026-02-10T17:26:54Z

.claude/settings.json

+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)"
+    ],


The deny rule Read(./.env.*) also blocks reading .env.development, which this repo uses for non-secret defaults and which is referenced by the documentation. Consider narrowing the deny list to just secret-bearing files (for example .env, .env.local, .env.*.local) so assistants can still read committed defaults while avoiding secrets.

Copilot · 2026-02-10T17:26:54Z

CLAUDE.md

+## Testing
+
+Run the test suite against a local InfluxDB 3 Core instance:
+
+```bash
+# Start InfluxDB 3 Core
+docker compose up -d influxdb3-core
+
+# Run tests
+yarn test
+```


This testing section implies yarn test requires a running InfluxDB 3 Core container. The current test suite mocks ../lib/influxdb and does not use a live database (__tests__/api.test.js), so these steps are misleading. Suggest either updating the docs to say tests are mocked, or converting tests to true integration tests.

Copilot · 2026-02-10T17:26:54Z

AGENTS.md

+### Running Tests
+
+```bash
+# Ensure InfluxDB 3 is running
+docker compose up -d influxdb3-core
+
+# Run test suite
+yarn test
+```


This “Running Tests” section instructs starting InfluxDB 3 before yarn test, but the Jest suite currently mocks the InfluxDB client and runs without a database (__tests__/api.test.js). Consider clarifying that tests are mocked (or convert them to integration tests if that’s the intent).

Copilot · 2026-02-10T17:26:54Z

.claude/skills/run-tests/SKILL.md

+name: run-tests
+description: Run API tests against InfluxDB 3 Core. Handles service initialization, database setup, and test execution.
+author: InfluxData
+version: "1.0"


This skill claims tests run “against InfluxDB 3 Core” and includes DB initialization steps, but the current Jest suite mocks ../lib/influxdb and runs without a real database (__tests__/api.test.js). Either update this skill to describe the mocked test workflow, or convert tests to true integration tests and remove the module mock.

Copilot · 2026-02-10T17:26:55Z

.claude/skills/run-tests/SKILL.md

+# Create auth database
+curl -X POST "http://localhost:8181/api/v3/configure/database" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"db": "iot_center_auth"}'
+
+# Verify databases exist
+curl "http://localhost:8181/api/v3/configure/database?format=json" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+### 3. Configure Environment
+
+Create `.env.local` if it doesn't exist:
+
+```bash
+cat > .env.local << EOF
+INFLUX_HOST=http://localhost:8181
+INFLUX_TOKEN=$(cat test/.influxdb3/core/.token)
+INFLUX_DATABASE=iot_center
+INFLUX_DATABASE_AUTH=iot_center_auth
+EOF


The auth database name is inconsistent with the rest of the repo defaults (INFLUX_DATABASE_AUTH=iot_center_devices in .env.development/README). Here it’s iot_center_auth in both the database creation step and the suggested .env.local, which will misconfigure the app unless users also change defaults. Please align on a single name.

claude and others added 12 commits February 9, 2026 16:56

Merge main to resolve package.json conflict

324063a

- Keep @influxdata/influxdb3-client ^2.0.0 (InfluxDB 3 migration) - Update next to ^16.1.5 (from main) - Remove old @influxdata/influxdb-client packages https://claude.ai/code/session_01Pga27ES6JQsJo1joSVZMJY

Merge branch 'main' into claude/influxdb3-core-migration-pMqwy

b878619

Update pages/api/devices/create.js

07c514a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update pages/api/devices/create.js

85b5b40

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge influxdb3-migration-v3 into influxdb3-core-migration

a640134

Merge remote-tracking branch 'origin/release/influxdb3-core-3.8.1' in…

a72bf4b

…to claude/influxdb3-core-migration-pMqwy

Copilot AI review requested due to automatic review settings February 10, 2026 17:00

Copilot started reviewing on behalf of jstirnaman February 10, 2026 17:00 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

jstirnaman commented Feb 10, 2026

View reviewed changes

AGENTS.md Show resolved Hide resolved

AGENTS.md Outdated Show resolved Hide resolved

CLAUDE.md Outdated Show resolved Hide resolved

Update CLAUDE.md

4b74cc5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 10, 2026 17:19

Update compose.yaml

7b98aaa

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of jstirnaman February 10, 2026 17:20 View session

jstirnaman and others added 2 commits February 10, 2026 11:20

Update AGENTS.md

49f0d96

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update AGENTS.md

1f093ea

jstirnaman added 2 commits February 10, 2026 11:20

Update CLAUDE.md

14d4f71

Update AGENTS.md

a2c5937

Copilot AI reviewed Feb 10, 2026

View reviewed changes

	\| `pages/api/measurements/index.js` \| Telemetry query endpoint \|
	\| `pages/api/measurements/index.js` \| Shared telemetry query helper \|

		## Purpose

		This skill guides running the IoT API test suite against a local InfluxDB 3 Core instance. It covers service setup, database creation, and test execution.

	echo "Token in .env.local: $(grep INFLUX_TOKEN .env.local)"
	echo "INFLUX_TOKEN env var: ${INFLUX_TOKEN:-'(not set)'}"

	- Never expose tokens in API responses
	- Never return the InfluxDB admin token in any API response or logs
	- Only return device tokens at registration (for example, `POST /api/devices/create`); never include them in GET/list or other read responses

	- Never exposed via public API responses
	- Not exposed via read/list endpoints and only returned once at registration (`POST /api/devices/create`)

Conversation

jstirnaman commented Feb 10, 2026

Summary

Changes

Claude Code Configuration

AI Assistant Documentation

Local Development

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants