instant-ruby 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b27a065c0c17c64d247486df6f8e7c7ad3ea865d9c93beca708b0bcd4e517c36
+  data.tar.gz: 595d188d47e68d4539f9fe984c76197b9062dd16a0cb9e4e4a5a7f80bf5bb500
+SHA512:
+  metadata.gz: ee348223c741d24422e53af75f2d7ca0a8be3673c71e1d7d2cee36cd78bfc74f73b91df56abd7b789cad71afe5233f0cea7371545b5a65f5625fc9f013c10fcf
+  data.tar.gz: f5b51e79f92ce3e6c9e8801c945089b96979dae8d2e041484c68aeb53fb4ad86cb123ad70c81a5d2aea36cd1b97d379988021439561e7bd41a679c52792d4560

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-21
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 John Paul
+
+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,172 @@
+# Instant Ruby
+
+A lightweight, idiomatic Ruby client for [InstantDB](https://instantdb.com).
+
+This gem provides a clean interface for InstantDB's Admin API, allowing you to query data, run transactions, and manage authentication from your Ruby backend.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'instant-ruby'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+## Quick Start
+
+```ruby
+require 'instant-ruby'
+
+# 1. Configure
+Instant::Client.configure do |config|
+  config.app_id = ENV['INSTANT_APP_ID']
+  config.admin_token = ENV['INSTANT_ADMIN_TOKEN']
+end
+
+# 2. Write data (Transaction)
+user_id = Instant::Client.id
+Instant::Client.transact do |tx|
+  tx.users[user_id].update(name: "Alice", email: "alice@example.com")
+end
+
+# 3. Query data
+users = Instant::Client.query({ users: { where: { email: "alice@example.com" } } })
+```
+
+## Configuration
+
+In a Rails application, place this in `config/initializers/instant.rb`.
+
+```ruby
+Instant::Client.configure do |config|
+  config.app_id = ENV['INSTANT_APP_ID']
+  config.admin_token = ENV['INSTANT_ADMIN_TOKEN']
+end
+```
+
+## Querying
+
+The query syntax mirrors the InstantDB client SDK. The gem automatically handles the `$` operator for modifiers (like `where`, `order`, `limit`), so you can write clean Ruby hashes.
+
+### Basic Queries
+
+```ruby
+# Fetch all tasks
+data = Instant::Client.query({ tasks: {} })
+
+# With modifiers (automatically normalized)
+data = Instant::Client.query({
+  tasks: {
+    where: { completed: false },
+    order: { created_at: "desc" },
+    limit: 10
+  }
+})
+
+# Nested relations
+data = Instant::Client.query({
+  users: {
+    posts: {
+      comments: { limit: 5 }
+    }
+  }
+})
+```
+
+### Helper Methods
+
+Convenience methods are available for common patterns:
+
+```ruby
+# Query all items in a namespace
+Instant::Client.query_all(:users)
+
+# Query with a simple where clause
+Instant::Client.query_where(:users, { email: "alice@example.com" })
+
+# Query by specific ID
+Instant::Client.query_by_id(:users, "user-id-123")
+```
+
+## Transactions
+
+Transactions allow you to write, update, and delete data atomically.
+
+### Block Syntax (Recommended)
+
+The block syntax allows for readable, chainable operations.
+
+```ruby
+user_id = Instant::Client.id
+team_id = "team-123"
+
+Instant::Client.transact do |tx|
+  # Create/Update a user and link to a team
+  tx.users[user_id].update(
+    name: "Alice",
+    role: "admin"
+  ).link(teams: team_id)
+
+  # Update the team in the same transaction
+  tx.teams[team_id].update(active: true)
+end
+```
+
+### Operations
+
+Available operations on an entity:
+
+- `update(attrs)`: Updates fields (merges).
+- `link(relation_name: id)`: Creates a link.
+- `unlink(relation_name: id)`: Removes a link.
+- `delete`: Deletes the entity.
+
+### Array Syntax
+
+For dynamic or programmatic transactions, you can pass an array of steps directly.
+
+```ruby
+steps = []
+steps << Instant::Client.tx.users["user-1"].delete
+steps << Instant::Client.tx.logs[Instant::Client.id].update(action: "deleted_user")
+
+Instant::Client.transact(steps)
+```
+
+## Authentication & Permissions
+
+### Managing Tokens
+
+```ruby
+# Create a refresh token for a specific email
+token = Instant::Client.create_token("alice@example.com")
+
+# Create a guest user (returns token and user ID)
+guest = Instant::Client.create_guest_user
+```
+
+### Impersonation
+
+You can run queries or transactions "as" a specific user to test permissions or perform actions on their behalf.
+
+```ruby
+# Fetch data as 'alice@example.com'
+Instant::Client.query(
+  { secrets: {} },
+  as_email: "alice@example.com"
+)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dqnamo/instant-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/instant-ruby.gemspec

@@ -0,0 +1,32 @@
+# instant-ruby.gemspec
+require_relative "lib/instant/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "instant-ruby"
+  spec.version = Instant::VERSION
+  spec.authors = ["Your Name"]
+  spec.email = ["your@email.com"]
+
+  spec.summary = "A Ruby client for InstantDB"
+  spec.description = "A Ruby client for InstantDB with support for queries and transactions."
+  spec.homepage = "https://github.com/dqnamo/instant-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  # Include only files in the git repo
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # No external dependencies needed!
+end

data/lib/instant/client.rb

@@ -0,0 +1,335 @@
+# lib/instant/client.rb
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+require "forwardable"
+
+module Instant
+  class Client
+    class Error < StandardError; end
+    class AuthenticationError < Error; end
+    class RequestError < Error; end
+
+    # Keys that should be moved into the "$" object automatically
+    MODIFIERS = [:where, :order, :limit, :offset, :first, :last, :after, :before].freeze
+
+    class Configuration
+      attr_accessor :app_id, :admin_token, :base_url
+
+      def initialize
+        @base_url = "https://api.instantdb.com"
+      end
+    end
+
+    class << self
+      extend Forwardable
+
+      # Expose instance methods as class methods for convenience
+      def_delegators :instance, :query, :query_all, :query_where, :query_by_id,
+                     :create_token, :create_guest_user, :verify_token,
+                     :transact
+
+      attr_writer :configuration
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def instance
+        @instance ||= new
+      end
+
+      def id
+        SecureRandom.uuid
+      end
+
+      # SDK-style transaction helper
+      def tx
+        TransactionProxy.new(instance)
+      end
+    end
+
+    def initialize(app_id: nil, admin_token: nil, base_url: nil)
+      @app_id = app_id || self.class.configuration.app_id
+      @admin_token = admin_token || self.class.configuration.admin_token
+      @base_url = base_url || self.class.configuration.base_url
+    end
+
+    # --- Query API ---
+
+    def query(query_obj, options = {})
+      # Apply magic to remove need for "$"
+      normalized = normalize_query(query_obj)
+      
+      endpoint = "/admin/query"
+      body = { query: normalized }
+      make_request(:post, endpoint, body, options)
+    end
+
+    def query_all(namespace, options = {})
+      query({ namespace => {} }, options)
+    end
+
+    def query_where(namespace, where_clause, options = {})
+      query({ namespace => { where: where_clause } }, options)
+    end
+
+    def query_by_id(namespace, id, options = {})
+      query_where(namespace, { id: id }, options)
+    end
+
+    # --- Transaction API ---
+
+    def transact(steps_or_options = {}, options = {}, &block)
+      steps = []
+      
+      if block_given?
+        # Block syntax: Instant::Client.transact { |tx| ... }
+        # steps_or_options is actually 'options' here
+        builder = TransactionBuilder.new(self)
+        yield(builder)
+        steps = builder.all_steps
+        options = steps_or_options
+      elsif steps_or_options.is_a?(Array)
+        # Array syntax: Instant::Client.transact([step1, step2])
+        # flatten handles nested arrays of steps
+        steps = steps_or_options.flat_map { |s| s.respond_to?(:steps) ? s.steps : s }
+      else
+        # No steps provided or incorrect usage
+        steps = []
+        options = steps_or_options
+      end
+
+      endpoint = "/admin/transact"
+      body = { steps: steps }
+      make_request(:post, endpoint, body, options)
+    end
+
+    # --- Auth API ---
+
+    def create_token(email)
+      endpoint = "/admin/refresh_tokens"
+      body = { email: email }
+      make_request(:post, endpoint, body)
+    end
+
+    def create_guest_user
+      endpoint = "/runtime/auth/sign_in_guest"
+      body = { "app-id" => @app_id }
+      
+      # We need a custom request here because this endpoint is public/runtime
+      uri = URI.parse("#{@base_url}#{endpoint}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      request.body = body.to_json
+      
+      response = http.request(request)
+      result = handle_response(response)
+      
+      # Symbolize keys manually for result
+      {
+        user_id: result.dig("user", "id"),
+        refresh_token: result["token"],
+        user: result["user"]
+      }
+    end
+
+    # --- Step Helpers ---
+    
+    def update_step(namespace, id, attrs)
+      [ "update", namespace, id, attrs ]
+    end
+
+    def merge_step(namespace, id, attrs)
+      [ "merge", namespace, id, attrs ]
+    end
+
+    def link_step(namespace, id, links)
+      [ "link", namespace, id, links ]
+    end
+
+    def unlink_step(namespace, id, links)
+      [ "unlink", namespace, id, links ]
+    end
+
+    def delete_step(namespace, id)
+      [ "delete", namespace, id ]
+    end
+
+    private
+
+    # Magic method to move specific keys into "$"
+    def normalize_query(obj)
+      return obj unless obj.is_a?(Hash)
+
+      # Recursively process values first
+      processed = obj.transform_values { |v| normalize_query(v) }
+
+      modifiers = {}
+      fields = {}
+
+      processed.each do |k, v|
+        key_sym = k.to_s.to_sym rescue nil
+        if key_sym && MODIFIERS.include?(key_sym)
+          modifiers[k] = v
+        else
+          fields[k] = v
+        end
+      end
+
+      if modifiers.any?
+        # Use string "$" key for JSON compatibility
+        existing_dollar = fields["$"] || fields[:"$"] || {}
+        fields["$"] = existing_dollar.merge(modifiers)
+      end
+
+      fields
+    end
+
+    def make_request(method, endpoint, body = nil, options = {})
+      uri = URI.parse("#{@base_url}#{endpoint}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = case method
+      when :post then Net::HTTP::Post.new(uri.path)
+      when :get then Net::HTTP::Get.new(uri.path)
+      else raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@admin_token}"
+      request["App-Id"] = @app_id
+
+      request["as-email"] = options[:as_email] if options[:as_email]
+      request["as-token"] = options[:as_token] if options[:as_token]
+      request["as-guest"] = options[:as_guest].to_s if options.key?(:as_guest)
+
+      request.body = body.to_json if body
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200..299
+        return {} if response.body.nil? || response.body.empty?
+        JSON.parse(response.body, symbolize_names: true)
+      when 401
+        raise AuthenticationError, "Authentication failed: #{response.body}"
+      when 400..499
+        raise RequestError, "Request failed (#{response.code}): #{response.body}"
+      when 500..599
+        raise Error, "Server error (#{response.code}): #{response.body}"
+      else
+        raise Error, "Unexpected response (#{response.code}): #{response.body}"
+      end
+    rescue JSON::ParserError => e
+      raise Error, "Failed to parse response: #{e.message}"
+    end
+
+    # --- Builder Classes ---
+
+    class TransactionBuilder
+      def initialize(client)
+        @client = client
+        @entity_builders = []
+      end
+
+      def method_missing(namespace, *args, &block)
+        if args.length == 1 && !block
+          # tx.users(id)
+          builder = EntityBuilder.new(@client, namespace.to_s, args.first)
+          @entity_builders << builder
+          builder
+        elsif args.empty?
+          # tx.users[id] via proxy
+          NamespaceProxy.new(@client, namespace.to_s, @entity_builders)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        true
+      end
+
+      def all_steps
+        @entity_builders.flat_map(&:steps)
+      end
+    end
+
+    class TransactionProxy
+      def initialize(client)
+        @client = client
+      end
+
+      def method_missing(namespace, *args, &block)
+        NamespaceProxy.new(@client, namespace.to_s, nil)
+      end
+      
+      def respond_to_missing?(method_name, include_private = false)
+        true
+      end
+    end
+
+    class NamespaceProxy
+      def initialize(client, namespace, entity_builders_list = nil)
+        @client = client
+        @namespace = namespace
+        @entity_builders_list = entity_builders_list
+      end
+
+      def [](id)
+        builder = EntityBuilder.new(@client, @namespace, id)
+        @entity_builders_list << builder if @entity_builders_list
+        builder
+      end
+    end
+
+    class EntityBuilder
+      attr_reader :steps
+
+      def initialize(client, namespace, id)
+        @client = client
+        @namespace = namespace
+        @id = id
+        @steps = []
+      end
+
+      def update(attrs)
+        @steps << @client.update_step(@namespace, @id, attrs)
+        self
+      end
+
+      def merge(attrs)
+        @steps << @client.merge_step(@namespace, @id, attrs)
+        self
+      end
+
+      def link(links)
+        @steps << @client.link_step(@namespace, @id, links)
+        self
+      end
+
+      def unlink(links)
+        @steps << @client.unlink_step(@namespace, @id, links)
+        self
+      end
+
+      def delete
+        @steps << @client.delete_step(@namespace, @id)
+        self
+      end
+    end
+  end
+end

data/lib/instant/version.rb

@@ -0,0 +1,4 @@
+# lib/instant/version.rb
+module Instant
+  VERSION = "0.2.0"
+end

data/lib/instant-ruby.rb

@@ -0,0 +1,10 @@
+# lib/instant-ruby.rb
+require "instant/version"
+require "instant/client"
+
+module Instant
+  class Error < StandardError; end
+  
+  # Delegate handy methods to the Client class for easy access
+  # e.g. Instant.config, Instant.connect, etc if desired
+end

data/sig/instant/ruby.rbs

@@ -0,0 +1,6 @@
+module Instant
+  module Ruby
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: instant-ruby
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Your Name
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-21 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby client for InstantDB with support for queries and transactions.
+email:
+- your@email.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- instant-ruby-0.1.0.gem
+- instant-ruby.gemspec
+- lib/instant-ruby.rb
+- lib/instant/client.rb
+- lib/instant/version.rb
+- sig/instant/ruby.rbs
+homepage: https://github.com/dqnamo/instant-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dqnamo/instant-ruby
+  source_code_uri: https://github.com/dqnamo/instant-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby client for InstantDB
+test_files: []