waha-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc9414c7b9bb51ef5a2e118d72f6b0d33bc099b91ea8b705a11f6c17d63ca7ac
+  data.tar.gz: 8fa5cba6397385326900b0d420a45fb2029c33350205c038046f0fd314588540
+SHA512:
+  metadata.gz: 69d17352f8e08d07e2d86948a31c7079ff7cdacb7b9bca0ac91f72a292caa6eb50e5f7c9a9ba90d4b7b4886cc3ba7683a544176a77c1f56e9de643c6852e935a
+  data.tar.gz: 29707e3dfac2eca128adc7ab801e5e062d523944a32db35d0500870fb46b4dfcedeb2c6523828108a0dc556735b91e129bcf1a60d6e6e17c3e176335773ac7f4

data/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+> [!NOTE]
+> **Changes:** <!-- Describe what has been changed in this PR and, most importantly, why it's changed. Use 3-5 bullet points. -->
+>
+
+> [!TIP]
+> **How to review:** <!-- Describe what the reviewer of this PR should be looking for and what results are expected. -->
+>
+
+> [!WARNING]
+> **Risks:** <!-- Is there any risk attached to merging this PR? Select the appropriate box. -->
+> - [x] none
+> - [ ] low
+> - [ ] high

data/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600
+        with:
+          ruby-version: 4.0.5
+          bundler-cache: true
+
+      - name: Run CI checks
+        run: bin/ci
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08
+        if: always()
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 30
+          if-no-files-found: ignore

data/.github/workflows/release.yml

@@ -0,0 +1,457 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    if: ${{ github.event.release.prerelease == false }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out release tag
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600
+        with:
+          ruby-version: 4.0.5
+          bundler-cache: true
+
+      - name: Validate release identity
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          fail() {
+            echo "::error::$1"
+            exit 1
+          }
+
+          [[ "$REPOSITORY" == "develoz-com/waha-ruby" ]] ||
+            fail "release workflow must run in develoz-com/waha-ruby"
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] ||
+            fail "release tag must match vX.Y.Z"
+
+          tag_sha="$(git rev-parse --verify "refs/tags/${RELEASE_TAG}^{commit}")"
+          head_sha="$(git rev-parse --verify HEAD)"
+          main_sha="$(git rev-parse --verify "refs/remotes/origin/main^{commit}")"
+
+          [[ "$tag_sha" == "$head_sha" ]] ||
+            fail "checked-out commit does not match ${RELEASE_TAG}"
+          [[ "$tag_sha" == "$RELEASE_SHA" ]] ||
+            fail "${RELEASE_TAG} does not match the release event SHA"
+          [[ "$tag_sha" == "$main_sha" ]] ||
+            fail "${RELEASE_TAG} is not the current origin/main commit"
+
+          version="$(ruby -Ilib -rwaha/version -e 'print Waha::VERSION')"
+          [[ "$RELEASE_TAG" == "v${version}" ]] ||
+            fail "${RELEASE_TAG} does not match Waha::VERSION ${version}"
+
+      - name: Run CI
+        run: bin/ci
+
+      - name: Validate changelog update
+        env:
+          PUBLISHED_AT: ${{ github.event.release.published_at }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          release_date="${PUBLISHED_AT%%T*}"
+          [[ "$release_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || {
+            echo "::error::release published_at must contain a YYYY-MM-DD date"
+            exit 1
+          }
+
+          bin/update_changelog \
+            --tag "$RELEASE_TAG" \
+            --date "$release_date" \
+            --repository "$REPOSITORY" \
+            --check \
+            CHANGELOG.md
+
+  publish:
+    needs: validate
+    if: ${{ github.event.release.prerelease == false && needs.validate.result == 'success' }}
+    runs-on: ubuntu-latest
+    environment: rubygems
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out immutable release commit
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      - name: Validate immutable release refs
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          fail() {
+            echo "::error::$1"
+            exit 1
+          }
+
+          [[ "$REPOSITORY" == "develoz-com/waha-ruby" ]] ||
+            fail "release workflow must run in develoz-com/waha-ruby"
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] ||
+            fail "release tag must match vX.Y.Z"
+
+          tag_sha="$(git rev-parse --verify "refs/tags/${RELEASE_TAG}^{commit}")"
+          head_sha="$(git rev-parse --verify HEAD)"
+          main_sha="$(git rev-parse --verify "refs/remotes/origin/main^{commit}")"
+
+          [[ "$head_sha" == "$RELEASE_SHA" ]] ||
+            fail "checked-out commit does not match the release event SHA"
+          [[ "$tag_sha" == "$RELEASE_SHA" ]] ||
+            fail "${RELEASE_TAG} does not match the release event SHA"
+          [[ "$main_sha" == "$RELEASE_SHA" ]] ||
+            fail "${RELEASE_TAG} is not the current origin/main commit"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600
+        with:
+          ruby-version: 4.0.5
+          bundler: none
+
+      - name: Validate gem version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+
+          version="$(ruby -Ilib -rwaha/version -e 'print Waha::VERSION')"
+          if [[ "$RELEASE_TAG" != "v${version}" ]]; then
+            echo "::error::${RELEASE_TAG} does not match Waha::VERSION ${version}"
+            exit 1
+          fi
+          printf 'VERSION=%s\n' "$version" >> "$GITHUB_ENV"
+
+      - name: Build exact gem
+        run: |
+          set -euo pipefail
+
+          gem_path="pkg/waha-ruby-${VERSION}.gem"
+          mkdir -p pkg
+          rm -f -- "$gem_path"
+          gem build waha-ruby.gemspec --output "$gem_path"
+          [[ -f "$gem_path" ]] || {
+            echo "::error::gem build did not create ${gem_path}"
+            exit 1
+          }
+          printf 'GEM_PATH=%s\n' "$gem_path" >> "$GITHUB_ENV"
+
+      - name: Inspect built gem
+        run: |
+          ruby -rrubygems/package <<'RUBY'
+          gem_path = ENV.fetch("GEM_PATH")
+          version = ENV.fetch("VERSION")
+          package = Gem::Package.new(gem_path)
+          package.verify
+          specification = package.spec
+
+          abort "expected gem name waha-ruby, got #{specification.name}" unless specification.name == "waha-ruby"
+          abort "expected gem version #{version}, got #{specification.version}" unless specification.version.to_s == version
+          abort "expected ruby platform, got #{specification.platform}" unless specification.platform.to_s == "ruby"
+          abort "expected no executables" unless specification.executables.empty?
+
+          files = package.contents
+          required_files = %w[
+            CHANGELOG.md
+            LICENSE.txt
+            README.md
+            lib/waha.rb
+            lib/waha/version.rb
+          ]
+          missing_files = required_files - files
+          abort "gem is missing required files: #{missing_files.join(', ')}" unless missing_files.empty?
+
+          excluded_files = %w[.gitignore .rspec Gemfile waha-ruby.gemspec]
+          excluded_prefixes = %w[bin/ spec/ docs/ templates/]
+          unexpected_files = files.select do |file|
+            excluded_files.include?(file) || excluded_prefixes.any? { |prefix| file.start_with?(prefix) }
+          end
+          abort "gem contains excluded files: #{unexpected_files.join(', ')}" unless unexpected_files.empty?
+          RUBY
+
+      - name: Check RubyGems version state
+        id: version-state
+        env:
+          RUN_ATTEMPT: ${{ github.run_attempt }}
+        run: |
+          set -euo pipefail
+
+          [[ "$RUN_ATTEMPT" =~ ^[1-9][0-9]*$ ]] || {
+            echo "::error::invalid workflow run attempt ${RUN_ATTEMPT}"
+            exit 1
+          }
+
+          api_url="https://rubygems.org/api/v2/rubygems/waha-ruby/versions/${VERSION}.json"
+          checks=12
+
+          status=""
+          for ((check = 1; check <= checks; check++)); do
+            status="$(curl \
+              --silent \
+              --show-error \
+              --location \
+              --connect-timeout 10 \
+              --max-time 30 \
+              --output /dev/null \
+              --write-out '%{http_code}' \
+              "$api_url")"
+
+            if [[ "$status" == "200" ]]; then
+              break
+            fi
+            [[ "$status" == "404" ]] || {
+              echo "::error::RubyGems API returned HTTP ${status}"
+              exit 1
+            }
+            if (( check < checks )); then
+              sleep 5
+            fi
+          done
+
+          if [[ "$status" == "200" ]]; then
+            echo "should-push=false" >> "$GITHUB_OUTPUT"
+            echo "waha-ruby ${VERSION} is already published; skipping gem push"
+          else
+            echo "should-push=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Configure RubyGems credentials
+        if: ${{ steps.version-state.outputs.should-push == 'true' }}
+        uses: rubygems/configure-rubygems-credentials@dc5a8d8553e6ee01fc26761a49e99e733d17954a
+
+      - name: Push exact gem
+        if: ${{ steps.version-state.outputs.should-push == 'true' }}
+        run: gem push "pkg/waha-ruby-${VERSION}.gem"
+
+      - name: Verify RubyGems API visibility
+        env:
+          SHOULD_PUSH: ${{ steps.version-state.outputs.should-push }}
+        run: |
+          set -euo pipefail
+
+          api_url="https://rubygems.org/api/v2/rubygems/waha-ruby/versions/${VERSION}.json"
+          api_response="$RUNNER_TEMP/waha-ruby-${VERSION}.json"
+          status=""
+
+          for ((check = 1; check <= 18; check++)); do
+            status="$(curl \
+              --silent \
+              --show-error \
+              --location \
+              --connect-timeout 10 \
+              --max-time 30 \
+              --output "$api_response" \
+              --write-out '%{http_code}' \
+              "$api_url")"
+
+            if [[ "$status" == "200" ]]; then
+              break
+            fi
+            [[ "$status" == "404" ]] || {
+              echo "::error::RubyGems API returned HTTP ${status}"
+              exit 1
+            }
+            if (( check < 18 )); then
+              sleep 5
+            fi
+          done
+
+          [[ "$status" == "200" ]] || {
+            echo "::error::waha-ruby ${VERSION} did not become visible through the RubyGems API"
+            exit 1
+          }
+
+          API_RESPONSE="$api_response" SHOULD_PUSH="$SHOULD_PUSH" ruby -rjson -rdigest <<'RUBY'
+          payload = JSON.parse(File.read(ENV.fetch("API_RESPONSE")))
+          version = ENV.fetch("VERSION")
+
+          abort "RubyGems API returned the wrong gem name" unless payload.fetch("name") == "waha-ruby"
+          abort "RubyGems API returned the wrong version" unless payload.fetch("version") == version
+          abort "RubyGems API returned the wrong platform" unless payload.fetch("platform") == "ruby"
+          abort "RubyGems API reports the release as yanked" if payload.fetch("yanked")
+
+          # Only verify SHA when we pushed the gem in this run
+          if ENV.fetch("SHOULD_PUSH") == "true"
+            gem_path = ENV.fetch("GEM_PATH")
+            expected_sha = Digest::SHA256.file(gem_path).hexdigest
+            abort "RubyGems API SHA does not match the built gem" unless payload.fetch("sha") == expected_sha
+          else
+            puts "Gem was already published; skipping SHA verification"
+          end
+          RUBY
+
+  finalize-changelog:
+    needs: publish
+    if: ${{ github.event.release.prerelease == false && needs.publish.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Check out main
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@003a5c4d8d6321bd302e38f6f0ec593f77f06600
+        with:
+          ruby-version: 4.0.5
+          bundler: none
+
+      - name: Validate main and release tag
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          fail() {
+            echo "::error::$1"
+            exit 1
+          }
+
+          [[ "$REPOSITORY" == "develoz-com/waha-ruby" ]] ||
+            fail "release workflow must run in develoz-com/waha-ruby"
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] ||
+            fail "release tag must match vX.Y.Z"
+
+          tag_sha="$(git rev-parse --verify "refs/tags/${RELEASE_TAG}^{commit}")"
+          head_sha="$(git rev-parse --verify HEAD)"
+          main_sha="$(git rev-parse --verify "refs/remotes/origin/main^{commit}")"
+
+          [[ "$tag_sha" == "$RELEASE_SHA" ]] ||
+            fail "${RELEASE_TAG} no longer matches the release event SHA"
+          [[ "$head_sha" == "$main_sha" ]] ||
+            fail "checked-out main does not match origin/main"
+
+          if [[ "$main_sha" == "$RELEASE_SHA" ]]; then
+            finalize_state="fresh"
+          else
+            parents="$(git show -s --format=%P "$main_sha")"
+            [[ "$parents" == "$RELEASE_SHA" ]] ||
+              fail "main is not the release commit or its single direct child"
+
+            subject="$(git show -s --format=%s "$main_sha")"
+            expected_subject="docs: finalize ${RELEASE_TAG} changelog"
+            [[ "$subject" == "$expected_subject" ]] ||
+              fail "the commit after the release has an unexpected subject"
+
+            changed_files="$(git diff-tree --no-commit-id --name-only -r "$main_sha")"
+            [[ "$changed_files" == "CHANGELOG.md" ]] ||
+              fail "the commit after the release must change only CHANGELOG.md"
+
+            finalize_state="already-finalized"
+          fi
+
+          version="$(ruby -Ilib -rwaha/version -e 'print Waha::VERSION')"
+          [[ "$RELEASE_TAG" == "v${version}" ]] ||
+            fail "${RELEASE_TAG} does not match Waha::VERSION ${version}"
+          printf 'FINALIZE_STATE=%s\n' "$finalize_state" >> "$GITHUB_ENV"
+
+      - name: Finalize changelog
+        env:
+          PUBLISHED_AT: ${{ github.event.release.published_at }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          release_date="${PUBLISHED_AT%%T*}"
+          [[ "$release_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || {
+            echo "::error::release published_at must contain a YYYY-MM-DD date"
+            exit 1
+          }
+
+          bin/update_changelog \
+            --tag "$RELEASE_TAG" \
+            --date "$release_date" \
+            --repository "$REPOSITORY" \
+            CHANGELOG.md
+
+      - name: Commit changelog if changed
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+
+          if [[ "$FINALIZE_STATE" == "already-finalized" ]]; then
+            working_tree="$(git status --porcelain --untracked-files=all)"
+            if [[ -n "$working_tree" ]]; then
+              echo "::error::changelog updater was not idempotent on the finalized commit"
+              exit 1
+            fi
+            echo "CHANGELOG.md is already finalized for ${RELEASE_TAG}"
+            exit 0
+          fi
+
+          [[ "$FINALIZE_STATE" == "fresh" ]] || {
+            echo "::error::unexpected changelog finalization state ${FINALIZE_STATE}"
+            exit 1
+          }
+
+          if git diff --quiet -- CHANGELOG.md; then
+            echo "CHANGELOG.md is already finalized for ${RELEASE_TAG}"
+            exit 0
+          fi
+
+          unexpected_files="$(git diff --name-only -- . ':(exclude)CHANGELOG.md')"
+          [[ -z "$unexpected_files" ]] || {
+            echo "::error::changelog finalization changed unexpected files: ${unexpected_files}"
+            exit 1
+          }
+          git diff --check
+
+          git add -- CHANGELOG.md
+          staged_files="$(git diff --cached --name-only)"
+          [[ "$staged_files" == "CHANGELOG.md" ]] || {
+            echo "::error::only CHANGELOG.md may be committed"
+            exit 1
+          }
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "docs: finalize ${RELEASE_TAG} changelog" -- CHANGELOG.md
+
+          tag_sha="$(git rev-parse --verify "refs/tags/${RELEASE_TAG}^{commit}")"
+          [[ "$tag_sha" == "$RELEASE_SHA" ]] || {
+            echo "::error::release tag changed during changelog finalization"
+            exit 1
+          }
+
+          git push origin HEAD:main

data/.reek.yml

@@ -0,0 +1,38 @@
+---
+exclude_paths:
+  - config
+  - db
+  - spec
+  - vendor
+
+detectors:
+  IrresponsibleModule:
+    enabled: false
+  UtilityFunction:
+    enabled: false
+  ControlParameter:
+    enabled: false
+  BooleanParameter:
+    enabled: false
+  FeatureEnvy:
+    enabled: false
+  TooManyStatements:
+    enabled: false
+  DuplicateMethodCall:
+    enabled: false
+  LongParameterList:
+    enabled: false
+  RepeatedConditional:
+    enabled: false
+  DataClump:
+    enabled: false
+  ManualDispatch:
+    enabled: false
+  MissingSafeMethod:
+    enabled: false
+  NilCheck:
+    enabled: false
+  UncommunicativeVariableName:
+    enabled: false
+  TooManyMethods:
+    max_methods: 25

data/.rubocop.yml

@@ -0,0 +1,73 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+
+require:
+  - rubocop-rubycw
+
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+    - ".git/**/*"
+    - "spec/fixtures/**/*"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "Rakefile"
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Exclude:
+    - "lib/waha/resources/messages.rb"
+
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/waha/resources/messages.rb"
+    - "lib/waha/transport/http_party.rb"
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/waha/resources/messages.rb"
+    - "lib/waha/transport/http_party.rb"
+
+Layout/LineLength:
+  Exclude:
+    - "waha-ruby.gemspec"
+
+RSpec/MultipleDescribes:
+  Exclude:
+    - "spec/waha/gows_spec.rb"
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 3
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+
+Style/SymbolArray:
+  EnforcedStyle: percent
+
+Style/WordArray:
+  EnforcedStyle: percent
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.5

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-09
+
+### Added
+
+- `Waha::Client` framework-agnostic SDK entry point with explicit
+  `base_url`, `api_key`, and `session` configuration, powered by Faraday transport.
+- Session lifecycle API: list, get, create, start, stop, restart, logout,
+  destroy, and pairing (`qr`, `request_code`).
+- Messaging API: send text/image/file/voice, edit message, mark chat seen,
+  start/stop typing, new-message-id, canonical message id helpers, list and
+  find messages.
+- Media API: media download with localhost-to-base URL rebasing.
+- Chats API: chat overview and chat message listing.
+- Contacts API: contact lookup and `check-exists` number verification.
+- Presence API: presence subscription per chat.
+- Webhook configuration API: idempotent session webhook registration.
+- `Waha::Webhook::Verifier` for sha512 HMAC webhook signature verification
+  with constant-time comparison.
+- Optional Rails adapter: controller concern for webhook verification and an
+  install generator for the `waha.rb` initializer.
+- Typed `Waha::Error` (operation, status, bounded redacted details) with
+  provider payload redaction.
+[Unreleased]: https://github.com/develoz-com/waha-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/develoz-com/waha-ruby/releases/tag/v0.1.0