active_shopify_graphql 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 209f2565381c7c64385baecde798f09270b6b1e55df8adaadfaa436c5d0890f2
+  data.tar.gz: 3813282f284e46583305ff2afb3ff143a69b8051a60bbcd6f42a567e562685e2
+SHA512:
+  metadata.gz: 338c590007e3510507cc197912db871979f77dc8a905cae118a29982a75fd8a74a178dde94ea25f7133857312e8b5d04820d99813c77efd803aadc51b8e49c37
+  data.tar.gz: 7f40d85c87be589b9c2df2461c035c43560e3c3ae6a343b2cac209c2c3974374acf7583b68261e1b1f259feb98e8c7310a3a6d11140e5c7314b34e98b9e6f385

data/.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Lint with RuboCop
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.4']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rubocop

data/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Run specs
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.2', '3.3', '3.4']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rspec

data/.rubocop.yml

@@ -0,0 +1,50 @@
+Style/StringLiterals:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false

data/AGENTS.md

@@ -0,0 +1,53 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Core code lives in `lib/active_shopify_graphql/`, with entrypoint `lib/active_shopify_graphql.rb` and loaders/associations split into focused files.
+- Tests sit in `spec/` using RSpec; shared config is in `spec/spec_helper.rb`.
+- Executables and setup utilities are in `bin/` (`bin/setup`, `bin/console`); Rake tasks are defined in `Rakefile`.
+
+## Build, Test, and Development Commands
+- `bundle install` — install dependencies (required before any other command).
+- `bin/setup` — project bootstrap (bundler + any initial prep).
+- `bundle exec rake spec` or just `bundle exec rspec` — run the test suite (default Rake task).
+- `bundle exec rubocop` — lint/format check using `.rubocop.yml`.
+- `bin/console` — interactive console with the gem loaded for quick experiments.
+
+## Coding Style & Naming Conventions
+- Ruby 3.2+; prefer idiomatic Ruby with 2-space indentation and frozen string literals already enabled.
+- Follow existing module/loader patterns under `ActiveShopifyGraphQL` (e.g., `AdminApiLoader`, `CustomerAccountApiLoader`).
+- Keep loaders small: expose `fragment` and `map_response_to_attributes` for clarity.
+- Use RuboCop defaults unless explicitly relaxed in `.rubocop.yml`; respect existing disables instead of re-enabling.
+
+## GID (Global ID) Handling
+- **Always** use `URI::GID.build` to construct Shopify GIDs programmatically; never concatenate strings manually.
+- **Always** use `URI::GID.parse` to validate and parse existing GID strings.
+- GID format: `gid://shopify/ModelName/id_value` where `app: 'shopify'`, `model_name:` is the GraphQL type (e.g., `Customer`, `Order`), and `model_id:` is the numeric or string identifier.
+- When building GIDs, use `model_name.name.demodulize` to extract the model type name (e.g., `Customer` from `ActiveShopifyGraphQL::Customer`) unless it's specified via the model's `graphql_type`.
+- When checking if a value is already a GID, parse it with `URI::GID.parse` and handle exceptions (`URI::InvalidURIError`, `URI::BadURIError`, `ArgumentError`).
+- Examples:
+  - Build: `URI::GID.build(app: "shopify", model_name: "Customer", model_id: 123).to_s` → `"gid://shopify/Customer/123"`
+  - Parse: `URI::GID.parse("gid://shopify/Customer/123")` → returns a `URI::GID` object
+  - Check validity: Wrap `URI::GID.parse` in a rescue block to detect non-GID strings.
+
+## Testing Guidelines
+- Framework: RSpec with documentation formatter (`.rspec`).
+- Place specs under `spec/` and name files `*_spec.rb` matching the class/module under test.
+- Do not use `let` or `before` blocks in specs; each test case should tell a complete story.
+- Use verifying doubles instead of normal doubles. Prefer `{instance|class}_{double|spy}` to `double` or `spy`
+- Prefer explicit model/loader fixtures; stub external Shopify calls rather than hitting the network.
+- Aim to cover happy path and schema edge cases (missing attributes, nil fragments). Add regression specs with minimal fixtures.
+
+## Commit & Pull Request Guidelines
+- Use short, imperative commit subjects (≈50 chars) with focused diffs; group related changes together.
+- Reference issues in commit messages or PR bodies when relevant.
+- PRs should include: what changed, why, and how to test (commands run, expected outcomes). Add screenshots only if user-facing behavior is affected.
+- When changing public APIs, update relevant documentation in the README.
+- Ensure CI-critical commands (`bundle exec rake spec`, `bundle exec rubocop`) pass locally before opening a PR.
+
+## Security & Configuration Tips
+- Verify Admin vs Customer Account API client selection when adding loaders; avoid leaking tokens between contexts.
+- If introducing new configuration knobs, document defaults and required environment variables in `README.md` and add minimal validation in configuration objects.
+
+## Implementation details
+- ALWAYS use inline argument values instead of arguments in the root query signature. This makes orders of magnitude easier working with enums, we move the burden on the developer instead of the gem.
+- Instead of passing down arguments in deep method chains, PREFER orthogonally using configurations. If you notice doing this in your work, consider extracting that to a config.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Nicolò Rebughini
+
+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.