calldata-lint 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71166882423774cca5b95058a33723ba96225dded3db7533ee50f175b17be985
+  data.tar.gz: 56d0642def573feac2a900e9a9c7cbacd0e34e105026745a44de1877dc98ca11
+SHA512:
+  metadata.gz: 46fac5a00dbcbcf0bd22462b37098b6d191a472b254d8f6281e305d870612b7526904eb088f3dcb1b258ede5de6638c1ff04f15fb780f3b09b6ddc176e119525
+  data.tar.gz: f1e07b4221515d12408850b321953240f6367e2925a28380cb3040cd7107a533969d109c07819e80f967f9434ae69b5ba052a1a32cdac4e4209880fb42719983

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 (2026-10-31)
+
+- Initial release.
+- Required-field checks: `call_id`, `started_at`, `direction`, `from_number`, `to_number` (extendable with `--require`).
+- Type checks for string/integer/object fields.
+- Value checks: ISO-8601 timestamp validity + UTC warning, E.164 phone-number warnings, negative/oversize `duration_seconds`, empty `transcript` warning, non-HTTPS `recording_url` warning.
+- `--strict` CI gating (warnings become errors), `--json` machine-readable output, multi-file support.
+- Zero runtime dependencies (Ruby stdlib only).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeveloApps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,86 @@
+# calldata-lint
+
+Lint structured call-data JSON before it reaches your systems.
+
+`calldata-lint` checks call-data records — AI voice-agent call exports, telephony webhooks, CRM call logs — and reports actionable findings before bad data lands in your downstream systems.
+
+## Why
+
+Voice agents and telephony integrations that "deliver structured call data to your systems" only help if the data is actually well-formed when it arrives. `calldata-lint` catches the common failure modes at the boundary: missing identifiers, unparseable or non-UTC timestamps, phone numbers in human formatting instead of E.164, negative or unit-confused durations, empty transcripts from failed captures, and insecure recording URLs.
+
+## What it checks
+
+**Required fields** (error if missing):
+
+| Field | Purpose |
+|---|---|
+| `call_id` | Unique call identifier |
+| `started_at` | ISO-8601 call start timestamp |
+| `direction` | `inbound` / `outbound` / `internal` |
+| `from_number` | Caller number |
+| `to_number` | Callee number |
+
+Add pipeline-specific required fields with `--require FIELD` (repeatable), e.g. `-r disposition -r recording_url`.
+
+**Value checks** (error):
+
+- `started_at` / `ended_at` must be valid ISO-8601 timestamps
+- `duration_seconds` must not be negative
+- wrong field types (string/integer/object)
+
+**Value checks** (warning):
+
+- non-UTC `started_at` offset (normalize before storage)
+- `from_number` / `to_number` not in E.164 format (`+18778972690`, not `(877) 897-2690`)
+- `duration_seconds` over 24 hours (unit confusion: minutes vs seconds)
+- `direction` outside the known set
+- present-but-empty `transcript` (often a capture failure)
+- non-HTTPS `recording_url`
+
+## Usage
+
+```sh
+# Lint one record
+calldata_lint.rb call.json
+
+# CI gate: fail on warnings too
+calldata_lint.rb --strict calls/*.json
+
+# Machine-readable output
+calldata_lint.rb --json call.json
+
+# Require pipeline-specific fields
+calldata_lint.rb -r disposition -r summary call.json
+```
+
+Exit codes: `0` clean, `1` findings at error level (or warnings with `--strict`), `2` usage error.
+
+Example output:
+
+```
+call.json: ERROR [started_at] 'started_at' is not a valid ISO-8601 timestamp: "Oct 31 2026"
+call.json: WARN [from_number] 'from_number' is not E.164 (expected +NNNNNNNNNNN): "(949) 555-1234"
+call.json: 2 finding(s), 1 error(s)
+```
+
+## Install
+
+```sh
+gem install calldata-lint
+```
+
+Zero runtime dependencies — Ruby stdlib only (`json`, `optparse`, `time`). Ruby 2.7+.
+
+## Testing
+
+```sh
+ruby test_calldata_lint.rb   # 18 tests
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).
+
+## Author
+
+Built by [DeveloApps](https://develoapps.com/) — application development that streamlines business processes and automates workflows. DeveloApps builds DeveloVoice, AI voice agents that answer inbound calls 24/7 and deliver structured call data to your systems.

data/calldata_lint.rb

@@ -0,0 +1,230 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# calldata-lint — lint structured call-data JSON before it reaches your systems.
+# Zero runtime dependencies: stdlib only (json, optparse, time).
+
+require 'json'
+require 'optparse'
+require 'time'
+
+module CalldataLint
+  VERSION = '1.0.0'
+
+  DEFAULT_REQUIRED = %w[call_id started_at direction from_number to_number].freeze
+  KNOWN_DIRECTION = %w[inbound outbound internal].freeze
+
+  Finding = Struct.new(:severity, :field, :message)
+
+  class Checker
+    # Optional extra required fields: transcript, summary, disposition,
+    # duration_seconds, recording_url, language
+    OPTIONAL_FIELDS = %w[
+      transcript summary disposition duration_seconds recording_url language
+      ended_at answered_by call_sid tags
+    ].freeze
+
+    def initialize(path:, strict: false, extra_required: [])
+      @path = path
+      @strict = strict
+      @required = DEFAULT_REQUIRED + extra_required
+    end
+
+    def check
+      findings = []
+      raw = read_file(findings)
+      return findings unless raw
+
+      record = parse_json(raw, findings)
+      return findings unless record.is_a?(Hash)
+
+      check_required(record, findings)
+      check_types(record, findings)
+      check_values(record, findings)
+      findings
+    end
+
+    private
+
+    def read_file(findings)
+      return File.read(@path) if File.file?(@path) && File.readable?(@path)
+
+      findings << Finding.new(:error, nil, "cannot read file: #{@path}")
+      nil
+    rescue StandardError => e
+      findings << Finding.new(:error, nil, "read failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def parse_json(raw, findings)
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      findings << Finding.new(:error, nil, "invalid JSON: #{e.message}")
+      nil
+    end
+
+    def check_required(record, findings)
+      @required.each do |field|
+        next unless record[field].nil? || (record[field].respond_to?(:empty?) && record[field].empty?)
+
+        findings << Finding.new(:error, field, "missing required field '#{field}'")
+      end
+    end
+
+    def check_types(record, findings)
+      check_string(record, 'call_id', findings)
+      check_string(record, 'direction', findings)
+      check_string(record, 'from_number', findings)
+      check_string(record, 'to_number', findings)
+      check_string(record, 'transcript', findings, optional: true)
+      check_string(record, 'summary', findings, optional: true)
+      check_integer(record, 'duration_seconds', findings, optional: true)
+      check_string(record, 'disposition', findings, optional: true)
+      check_string(record, 'recording_url', findings, optional: true)
+      check_string(record, 'language', findings, optional: true)
+      check_hash(record, 'tags', findings, optional: true)
+    end
+
+    def check_values(record, findings)
+      ts = record['started_at']
+      if ts.is_a?(String)
+        if iso8601?(ts)
+          findings << Finding.new(:warn, 'started_at', "'started_at' is not UTC (offset #{ts[/([+-]\d{2}:\d{2}|Z)$/] || 'missing'})") unless ts.end_with?('Z') || ts.end_with?('+00:00')
+        else
+          findings << Finding.new(:error, 'started_at', "'started_at' is not a valid ISO-8601 timestamp: #{ts.inspect}")
+        end
+      end
+
+      ets = record['ended_at']
+      if ets.is_a?(String) && !iso8601?(ets)
+        findings << Finding.new(:error, 'ended_at', "'ended_at' is not a valid ISO-8601 timestamp: #{ets.inspect}")
+      end
+
+      dir = record['direction']
+      if dir.is_a?(String) && !KNOWN_DIRECTION.include?(dir.downcase)
+        findings << Finding.new(:warn, 'direction', "'direction' is unusual: #{dir.inspect} (known: #{KNOWN_DIRECTION.join(', ')})")
+      end
+
+      %w[from_number to_number].each do |num_field|
+        num = record[num_field]
+        next unless num.is_a?(String) && !num.empty?
+
+        unless e164?(num)
+          findings << Finding.new(:warn, num_field, "'#{num_field}' is not E.164 (expected +NNNNNNNNNNN): #{num.inspect}")
+        end
+      end
+
+      dur = record['duration_seconds']
+      findings << Finding.new(:error, 'duration_seconds', "'duration_seconds' is negative: #{dur}") if dur.is_a?(Integer) && dur.negative?
+      if dur.is_a?(Integer) && dur > 86_400
+        findings << Finding.new(:warn, 'duration_seconds', "'duration_seconds' exceeds 24h (#{dur}) — verify unit is seconds")
+      end
+
+      tr = record['transcript']
+      if tr == ''
+        findings << Finding.new(:warn, 'transcript', "'transcript' is present but empty — a call with no transcript may indicate a capture failure")
+      end
+
+      ru = record['recording_url']
+      if ru.is_a?(String) && !ru.empty? && !ru.start_with?('https://')
+        findings << Finding.new(:warn, 'recording_url', "'recording_url' is not HTTPS: #{ru.inspect}")
+      end
+    end
+
+    def check_string(record, field, findings, optional: false)
+      value = record[field]
+      return if value.nil? && optional
+
+      findings << Finding.new(:error, field, "'#{field}' must be a string, got #{value.class}") unless value.is_a?(String)
+    end
+
+    def check_integer(record, field, findings, optional: false)
+      value = record[field]
+      return if value.nil? && optional
+
+      unless value.is_a?(Integer) || (value.is_a?(Float) && value == value.to_i)
+        findings << Finding.new(:error, field, "'#{field}' must be an integer, got #{value.class}")
+      end
+    end
+
+    def check_hash(record, field, findings, optional: false)
+      value = record[field]
+      return if value.nil? && optional
+
+      findings << Finding.new(:error, field, "'#{field}' must be an object, got #{value.class}") unless value.is_a?(Hash)
+    end
+
+    def iso8601?(value)
+      Time.iso8601(value)
+      true
+    rescue StandardError
+      false
+    end
+
+    def e164?(value)
+      !value.match(/\A\+?[1-9]\d{7,14}\z/).nil?
+    end
+  end
+
+  class CLI
+    def run(argv = ARGV)
+      paths = []
+      strict = false
+      json_out = false
+      extra_required = []
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: calldata-lint [options] FILE.json [FILE2.json ...]'
+        opts.separator('')
+        opts.separator 'Lint structured call-data JSON records (AI voice-agent call exports,'
+        opts.separator 'telephony webhooks, CRM call logs) before they reach your systems.'
+        opts.separator('')
+        opts.separator 'Options:'
+        opts.on('-r', '--require FIELD', 'Add an extra required field (repeatable)') { |f| extra_required << f }
+        opts.on('--strict', 'Treat warnings as errors (CI gate)') { strict = true }
+        opts.on('--json', 'Output findings as JSON') { json_out = true }
+        opts.on('-v', '--version', 'Show version') do
+          puts VERSION
+          return 0
+        end
+        opts.on('-h', '--help', 'Show help') do
+          puts opts
+          return 0
+        end
+      end
+      paths = parser.parse(argv)
+
+      if paths.empty?
+        warn parser.banner
+        return 2
+      end
+
+      all_results = {}
+      exit_code = 0
+      paths.each do |path|
+        findings = Checker.new(path: path, strict: strict, extra_required: extra_required).check
+        errors = findings.count { |f| f.severity == :error || (strict && f.severity == :warn) }
+        all_results[path] = { 'errors' => errors, 'findings' => findings.map { |f| { 'severity' => f.severity.to_s, 'field' => f.field, 'message' => f.message } } }
+        exit_code = 1 if errors.positive?
+      end
+
+      if json_out
+        puts JSON.pretty_generate(all_results)
+      else
+        all_results.each do |path, result|
+          result['findings'].each do |f|
+            puts "#{path}: #{f['severity'].upcase} [#{f['field'] || 'file'}] #{f['message']}"
+          end
+          if result['findings'].empty?
+            puts "#{path}: OK (0 findings)"
+          else
+            puts "#{path}: #{result['findings'].size} finding(s), #{result['errors']} error(s)"
+          end
+        end
+      end
+      exit_code
+    end
+  end
+end
+
+exit(CalldataLint::CLI.new.run(ARGV)) if __FILE__ == $PROGRAM_NAME

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: calldata-lint
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- DeveloApps
+bindir: "."
+cert_chain: []
+date: 2026-10-31 00:00:00.000000000 Z
+dependencies: []
+description: calldata-lint checks structured call-data JSON records (AI voice-agent
+  call exports, telephony webhooks, CRM call logs) before they reach your systems.
+  It verifies required fields (call_id, started_at, direction, from_number, to_number),
+  field types, ISO-8601 timestamp validity and UTC normalization, E.164 phone-number
+  format, negative/oversize duration checks, empty-transcript capture warnings, and
+  HTTPS recording URLs. Supports extra required fields, --strict CI gating, --json
+  output, and multiple files. Zero runtime dependencies — stdlib only (json, optparse,
+  time).
+email:
+- marky@develoapps.com
+executables:
+- calldata_lint.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- "./calldata_lint.rb"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- calldata_lint.rb
+homepage: https://develoapps.com/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://develoapps.com/
+  source_code_uri: https://develoapps.com/
+  changelog_uri: https://develoapps.com/
+rdoc_options: []
+require_paths:
+- "."
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: 'Lint structured call-data JSON: required fields, types, ISO-8601 timestamps,
+  E.164 numbers, CI exit codes.'
+test_files: []