autocontext-oil-gas-connectors

Optional connector target presets, Ares-style import presets, and HTTP/API adapter factories for autocontext-oil-gas-core.

This package keeps the core package vendor-neutral while making org integrations easier to wire.

Install

npm install autocontext-oil-gas-connectors autocontext-oil-gas-core

Targets

• Public/regulatory: EIA, BSEE, Texas RRC, NDIC, Oklahoma OCC, CalGEM, FracFocus.
• Licensed/vendor: Enverus, Wood Mackenzie, S&P Global Commodity Insights, IHS/S&P North American Upstream API-style integrations.
• Backoffice exports: Ares-style CSV/JSON production, LOS/JIB, budget, and revenue import presets.

Key APIs

• CONNECTOR_TARGETS
• listConnectorTargets
• inspectAresImportFile
• inspectAresImportRows
• loadAresProductionDatasetFromFile
• loadAresLeaseOperatingStatementFromFile
• loadAresLeaseOperatingBudgetFromFile
• loadAresRevenueStatementFromFile
• runAresMonthlyOperatingReview
• createConnectorSourcePack
• createTargetHttpProductionConnector
• createPaginatedHttpProductionConnector
• createEnverusProductionConnector
• createEiaProductionConnector
• createWoodMacProductionConnector
• createSpGlobalProductionConnector
• createIhsNorthAmericanProductionConnector
• validateConnectorConfig
• createProductionConnectorFromConfig
• createConnectorSourcePackFromConfig
• smokeTestConnectorConfig
• runConnectorContractTest
• connectorLiveContractReadiness
• listConnectorConfigEnvironmentVariables
• renderConnectorContractTestMarkdown

Ares-style imports

import { inspectAresImportFile, loadAresLeaseOperatingStatementFromFile } from "autocontext-oil-gas-connectors";

const inspection = await inspectAresImportFile("ares-los.csv", "lease_operating_statement", {
  fieldMapping: { wellId: "Asset", month: "Acct Month", amountUsd: "Net Cost" },
});
if (inspection.status === "fail") throw new Error(`Missing columns: ${inspection.missingRequiredFields.join(", ")}`);
const statement = await loadAresLeaseOperatingStatementFromFile("ares-los.csv");

CLI inspection:

oil-gas-impact-connectors inspect-ares-import --kind revenue_statement --input ares-revenue.csv --mapping mapping.json --json
# Generic alias for non-Ares exports using the same mapping file shape:
oil-gas-impact-connectors inspect-import --profile custom --kind revenue_statement --input export.csv --mapping mapping.json --json
# Write a fill-in mapping template from the selected import kind:
oil-gas-impact-connectors inspect-import --profile custom --kind revenue_statement --input export.csv --write-mapping-template mapping.template.json

For one-call monthly review over Ares-style exports:

oil-gas-impact-connectors run-ares-monthly-operating-review \
  --production ares-production.csv \
  --statement ares-los.csv \
  --budget ares-budget.csv \
  --revenue ares-revenue.csv \
  --ownership ownership.json \
  --run-dir runs/ares-monthly
# Generic alias:
oil-gas-impact-connectors run-monthly-operating-review-import --profile custom \
  --production production.csv --statement costs.csv --revenue revenue.csv --run-dir runs/imported-monthly

Or use runAresMonthlyOperatingReview from TypeScript.

These are file import presets only, not direct Ares API/auth connectors. Inspect first, then pass fieldMapping/--mapping when your export headers differ.

Connector contract tests

Use runConnectorContractTest to verify an org/vendor connector config without making live network calls by default. The harness validates credential-safe config, creates a source pack, runs a mockable smoke test, checks canonical fields/source IDs, and verifies configured credential values are redacted from the result.

import { runConnectorContractTest } from "autocontext-oil-gas-connectors";

const result = await runConnectorContractTest(connectorConfig, {
  mode: "mock",
  env: { ENVERUS_API_KEY: process.env.ENVERUS_API_KEY },
  fetchImpl: mockFetch,
  requiredFields: ["wellId", "month", "sourceId"],
  expectedSourceId: "enverus",
});

Live connector checks are opt-in. Gate them with connectorLiveContractReadiness; it requires OIL_GAS_CONNECTOR_LIVE_TESTS=true and all env-backed config variables before live network calls should be attempted.

OIL_GAS_CONNECTOR_LIVE_TESTS=true ENVERUS_API_KEY=... node your-contract-test.mjs

Do not put literal secrets in connector JSON; use auth.env and secret-manager/environment injection.

Principle

Use this package for target metadata, credential-safe adapter wiring, mockable HTTP integration, and connector contract checks. Keep actual credentials, contract-specific endpoints, and licensed data handling inside the deploying organization.