edgebase_admin 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7788c6699a8440a552520aaaf8f7374d52b8fbfe41888b119686f56ddff67e91
+  data.tar.gz: 1006a04397e2ff7b73049156f853f7b6a566e2b5cd01a14a57154dab2fb3d7bc
+SHA512:
+  metadata.gz: 16c9a66d72b3c0b8440efba908b01b8d9a99aa5bd44f53cbe5efd48fb5acf5d610f6f0b67d611c6bc020885461b46f15d24af652bab7d6d5d466a85c0b78f284
+  data.tar.gz: dc86005559bc4a81e7553d02aea3a501b556bacc1751051d50f4d091184f7c9e4a8c501138851b3e07b367d8dbe4301bdaa55955e6f178d0b00e05eb1b7d1c2f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 melodysdreamj
+
+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,176 @@
+# EdgeBase Ruby Admin SDK
+
+Trusted server-side Ruby SDK for EdgeBase.
+
+Use `edgebase_admin` from backend apps, scripts, cron jobs, and other trusted Ruby runtimes that hold a Service Key. It exposes admin auth, database access, raw SQL, storage, push, analytics, functions, and native edge resources.
+
+Ruby uses a synchronous, object-oriented API. Most methods return values directly rather than promises or futures.
+
+## Documentation Map
+
+Use this README for a fast overview, then jump into the docs when you need depth:
+
+- [SDK Overview](https://edgebase.fun/docs/sdks)
+  Install commands and the public SDK matrix
+- [Admin SDK](https://edgebase.fun/docs/sdks/client-vs-server)
+  Trusted-server boundaries and admin-only capabilities
+- [Admin SDK Reference](https://edgebase.fun/docs/admin-sdk/reference)
+  Cross-language examples for auth, database, storage, functions, push, and analytics
+- [Admin User Management](https://edgebase.fun/docs/authentication/admin-users)
+  Create, update, delete, and manage users with a Service Key
+- [Database Admin SDK](https://edgebase.fun/docs/database/admin-sdk)
+  Table queries, filters, pagination, batch writes, and raw SQL
+- [Storage](https://edgebase.fun/docs/storage/upload-download)
+  Uploads, downloads, metadata, and signed URLs
+- [Analytics Admin SDK](https://edgebase.fun/docs/analytics/admin-sdk)
+  Request metrics, event tracking, and event queries
+- [Push Admin SDK](https://edgebase.fun/docs/push/admin-sdk)
+  Push send, topic broadcast, token inspection, and logs
+- [Native Resources](https://edgebase.fun/docs/server/native-resources)
+  KV, D1, Vectorize, and other trusted edge-native resources
+
+## For AI Coding Assistants
+
+This package includes an `llms.txt` file for AI-assisted development.
+
+Use it when you want an agent or code assistant to:
+
+- keep Service Keys on trusted servers
+- use the real Ruby method names and keyword arguments
+- avoid copying JS promise-based examples into Ruby
+- know when to use `admin_auth` versus the `auth` alias
+
+You can find it:
+
+- in this repository: [llms.txt](https://github.com/edge-base/edgebase/blob/main/packages/sdk/ruby/packages/admin/llms.txt)
+- in your environment after install, inside the `edgebase_admin` package directory as `llms.txt`
+
+## Installation
+
+```bash
+gem install edgebase_admin
+```
+
+If you use Bundler, add `edgebase_admin` to your Gemfile and run `bundle install`.
+
+## Quick Start
+
+```ruby
+require "edgebase_admin"
+
+admin = EdgebaseAdmin::AdminClient.new(
+  "https://your-project.edgebase.fun",
+  service_key: ENV.fetch("EDGEBASE_SERVICE_KEY")
+)
+
+users = admin.admin_auth.list_users(limit: 20)
+
+rows = admin.sql(
+  "shared",
+  "SELECT id, title FROM posts WHERE status = ?",
+  ["published"]
+)
+
+bucket = admin.storage.bucket("avatars")
+bucket.upload("user-1.jpg", "binary-data", content_type: "image/jpeg")
+
+admin.push.send("user-1", {
+  "title" => "Deployment finished",
+  "body" => "Your content is live."
+})
+```
+
+## Core API
+
+Once you create an admin client, these are the main surfaces you will use:
+
+- `admin.db(namespace = "shared", instance_id = nil)`
+  Server-side database access
+- `admin.admin_auth`
+  Admin user management
+- `admin.auth`
+  Alias for `admin.admin_auth`
+- `admin.sql(namespace = "shared", query, params = nil, instance_id: nil)`
+  Raw SQL execution
+- `admin.storage`
+  Server-side storage access
+- `admin.functions`
+  Call app functions from trusted code
+- `admin.push`
+  Send push notifications
+- `admin.analytics`
+  Query analytics and track server-side events
+- `admin.kv(namespace)`, `admin.d1(database)`, `admin.vector(index)`
+  Access platform resources from trusted code
+- `admin.broadcast(channel, event, payload = {})`
+  Server-side database-live broadcast
+- `admin.destroy`
+  No-op cleanup hook
+
+## Database Access
+
+```ruby
+posts = admin.db("app").table("posts")
+rows = posts.where("status", "==", "published").get
+```
+
+For instance databases, pass the instance id as the second argument:
+
+```ruby
+admin.db("workspace", "ws-123")
+admin.db("user", "user-123")
+```
+
+## Admin Users
+
+```ruby
+created = admin.admin_auth.create_user(
+  email: "admin@example.com",
+  password: "secure-pass-123",
+  data: { "displayName" => "June" }
+)
+
+admin.admin_auth.set_custom_claims(created["id"], {
+  "role" => "moderator"
+})
+
+users = admin.admin_auth.list_users(limit: 20)
+```
+
+## Raw SQL
+
+```ruby
+shared_rows = admin.sql(
+  "shared",
+  "SELECT 1 AS ok"
+)
+
+workspace_rows = admin.sql(
+  "workspace",
+  "SELECT * FROM documents WHERE status = ?",
+  ["published"],
+  instance_id: "ws-123"
+)
+```
+
+## Push And Analytics
+
+```ruby
+admin.push.send("user-123", {
+  "title" => "Hello",
+  "body" => "From the admin SDK"
+})
+
+overview = admin.analytics.overview("range" => "7d")
+```
+
+## Choose The Right Package
+
+| Package | Use it for |
+| --- | --- |
+| `edgebase_admin` | Trusted server-side Ruby code with Service Key access |
+| `edgebase_core` | Lower-level primitives for custom integrations |
+
+## License
+
+MIT

data/lib/edgebase_admin/admin_auth.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "edgebase_core"
+
+module EdgebaseAdmin
+  # Admin auth — server-side user management via Service Key.
+  #
+  #   user = admin.admin_auth.get_user("user-id")
+  #   new_user = admin.admin_auth.create_user(email: "admin@example.com", password: "secure")
+  #   admin.admin_auth.set_custom_claims("user-id", { "role" => "pro" })
+  #   admin.admin_auth.revoke_all_sessions("user-id")
+  class AdminAuthClient
+    def initialize(client)
+      @client = client
+    end
+
+    def get_user(user_id)
+      require_service_key!
+      unwrap_user(@client.get("/auth/admin/users/#{user_id}"))
+    end
+
+    def create_user(email = nil, password = nil, data: nil, **kwargs)
+      require_service_key!
+      body = normalize_create_user_payload(email, password, data, kwargs)
+      unwrap_user(@client.post("/auth/admin/users", body))
+    end
+
+    def update_user(user_id, data)
+      require_service_key!
+      unwrap_user(@client.patch("/auth/admin/users/#{user_id}", data))
+    end
+
+    def delete_user(user_id)
+      require_service_key!
+      @client.delete("/auth/admin/users/#{user_id}")
+    end
+
+    def list_users(limit: 20, cursor: nil)
+      require_service_key!
+      params = { "limit" => limit.to_s }
+      params["cursor"] = cursor if cursor
+      result = @client.get("/auth/admin/users", params: params)
+      result.is_a?(Hash) ? result : { "users" => [], "cursor" => nil }
+    end
+
+    def set_custom_claims(user_id, claims)
+      require_service_key!
+      unwrap_user(@client.put("/auth/admin/users/#{user_id}/claims", claims))
+    end
+
+    def revoke_all_sessions(user_id)
+      require_service_key!
+      @client.post("/auth/admin/users/#{user_id}/revoke")
+    end
+
+    def disable_mfa(user_id)
+      require_service_key!
+      @client.delete("/auth/admin/users/#{user_id}/mfa")
+    end
+
+    private
+
+    def normalize_create_user_payload(email, password, data, kwargs)
+      if email.is_a?(Hash) && password.nil? && data.nil? && kwargs.empty?
+        return stringify_hash(email)
+      end
+
+      body = stringify_hash(kwargs)
+      body["email"] = email if email
+      body["password"] = password if password
+      body["data"] = data if data
+      body
+    end
+
+    def stringify_hash(value)
+      value.each_with_object({}) do |(key, val), result|
+        result[key.to_s] = val
+      end
+    end
+
+    def unwrap_user(value)
+      return value["user"] if value.is_a?(Hash) && value["user"].is_a?(Hash)
+
+      value
+    end
+
+    def require_service_key!
+      sk = @client.instance_variable_get(:@service_key)
+      return if sk && !sk.empty?
+
+      raise EdgebaseCore::EdgeBaseError.new(
+        403,
+        "Service Key required for admin operations. " \
+        "Pass service_key: when constructing AdminClient."
+      )
+    end
+  end
+end

data/lib/edgebase_admin/admin_client.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "edgebase_core"
+require_relative "admin_auth"
+require_relative "kv_client"
+require_relative "d1_client"
+require_relative "vectorize_client"
+require_relative "push_client"
+require_relative "functions_client"
+require_relative "analytics_client"
+
+module EdgebaseAdmin
+  # DB namespace block reference for table access.
+  #
+  # Obtained via `admin.db("shared")`.
+  class DbRef
+    attr_reader :_namespace, :_instance_id
+
+    def initialize(core, namespace, instance_id = nil)
+      @core = core
+      @_namespace = namespace
+      @_instance_id = instance_id
+    end
+
+    # Get a TableRef for the named table.
+    def table(name)
+      EdgebaseCore::TableRef.new(
+        @core, name,
+        namespace: @_namespace,
+        instance_id: @_instance_id
+      )
+    end
+  end
+
+  # Unified admin client — db, storage, auth access via Service Key.
+  #
+  #   admin = EdgebaseAdmin::AdminClient.new("http://localhost:8688", service_key: ENV.fetch("EDGEBASE_SERVICE_KEY"))
+  #   table = admin.db("shared").table("posts")
+  #   record = table.insert({ "title" => "Hello" })
+  #
+  #   bucket = admin.storage.bucket("documents")
+  #   bucket.upload("file.txt", "Hello", content_type: "text/plain")
+  class AdminClient
+    attr_reader :admin_auth
+
+    def initialize(base_url, service_key:)
+      @http = EdgebaseCore::HttpClient.new(base_url, service_key: service_key)
+      @core = EdgebaseCore::GeneratedDbApi.new(@http)
+      @admin_auth = AdminAuthClient.new(@http)
+    end
+
+    # Get a DbRef for the given namespace.
+    def db(namespace = "shared", instance_id: nil)
+      DbRef.new(@core, namespace, instance_id)
+    end
+
+    # Get the StorageClient for file operations.
+    def storage
+      EdgebaseCore::StorageClient.new(@http)
+    end
+
+    # Get a KvClient for the named KV namespace.
+    def kv(namespace)
+      KvClient.new(@http, namespace)
+    end
+
+    # Get a D1Client for the named D1 database.
+    def d1(database)
+      D1Client.new(@http, database)
+    end
+
+    # Get a VectorizeClient for the named Vectorize index.
+    def vector(index)
+      VectorizeClient.new(@http, index)
+    end
+
+    # Get a PushClient for push notification operations.
+    def push
+      PushClient.new(@http)
+    end
+
+    # Get a FunctionsClient for calling app functions.
+    def functions
+      FunctionsClient.new(@http)
+    end
+
+    # Get an AnalyticsClient for metrics and custom event tracking.
+    def analytics
+      AnalyticsClient.new(@core, EdgebaseAdmin::GeneratedAdminApi.new(@http))
+    end
+
+    # Execute raw SQL via DatabaseDO.
+    #
+    #   rows = admin.sql("posts",
+    #     "SELECT authorId, COUNT(*) as cnt FROM posts GROUP BY authorId ORDER BY cnt DESC LIMIT ?",
+    #     [10])
+    def sql(namespace = "shared", query = nil, params = nil, instance_id: nil)
+      if !query.is_a?(String) || query.strip.empty?
+        raise ArgumentError, "Invalid sql() signature: query must be a non-empty string"
+      end
+
+      body = {
+        "namespace" => namespace,
+        "sql" => query,
+        "params" => params || [],
+      }
+      body["id"] = instance_id if instance_id
+      admin_core = EdgebaseAdmin::GeneratedAdminApi.new(@http)
+      result = admin_core.execute_sql(body)
+      return result["rows"] if result.is_a?(Hash) && result["rows"].is_a?(Array)
+      return result["items"] if result.is_a?(Hash) && result["items"].is_a?(Array)
+      return result["results"] if result.is_a?(Hash) && result["results"].is_a?(Array)
+
+      result
+    end
+
+    # Send a broadcast message to a database-live channel.
+    #
+    #   admin.broadcast("notifications", "alert", { "message" => "Maintenance in 5 min" })
+    def broadcast(channel, event, payload = {})
+      admin_core = EdgebaseAdmin::GeneratedAdminApi.new(@http)
+      admin_core.database_live_broadcast({
+        "channel" => channel,
+        "event" => event,
+        "payload" => payload
+      })
+    end
+
+    # Stateless HTTP client; nothing to tear down, but final-suite runners
+    # expect every admin SDK to expose a destroy/cleanup hook.
+    def destroy
+      nil
+    end
+  end
+end

data/lib/edgebase_admin/analytics_client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module EdgebaseAdmin
+  class AnalyticsClient
+    def initialize(core, admin_core)
+      @methods = EdgebaseCore::GeneratedAnalyticsMethods.new(core)
+      @admin_core = admin_core
+    end
+
+    def overview(options = {})
+      result = @admin_core.query_analytics(query: build_query("overview", options))
+      result.is_a?(Hash) ? result : {}
+    end
+
+    def time_series(options = {})
+      result = @admin_core.query_analytics(query: build_query("timeSeries", options))
+      result.is_a?(Hash) ? Array(result["timeSeries"]) : []
+    end
+
+    def breakdown(options = {})
+      result = @admin_core.query_analytics(query: build_query("breakdown", options))
+      result.is_a?(Hash) ? Array(result["breakdown"]) : []
+    end
+
+    def top_endpoints(options = {})
+      result = @admin_core.query_analytics(query: build_query("topEndpoints", options))
+      result.is_a?(Hash) ? Array(result["topItems"]) : []
+    end
+
+    def track(name, properties = {}, user_id: nil)
+      event = {
+        "name" => name,
+        "timestamp" => (Time.now.to_f * 1000).to_i
+      }
+      event["properties"] = properties unless properties.nil? || properties.empty?
+      event["userId"] = user_id if user_id
+      track_batch([event])
+    end
+
+    def track_batch(events)
+      normalized = Array(events).map do |event|
+        payload = event.dup
+        payload["timestamp"] ||= (Time.now.to_f * 1000).to_i
+        payload
+      end
+      return if normalized.empty?
+
+      @methods.track({ "events" => normalized })
+    end
+
+    def query_events(options = {})
+      @admin_core.query_custom_events(query: options)
+    end
+
+    private
+
+    def build_query(metric, options)
+      { "metric" => metric }.merge(options || {})
+    end
+  end
+end

data/lib/edgebase_admin/d1_client.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "edgebase_core"
+
+module EdgebaseAdmin
+  # Client for a user-defined D1 database.
+  #
+  #   rows = admin.d1("analytics").exec("SELECT * FROM events WHERE type = ?", ["pageview"])
+  class D1Client
+    def initialize(http_client, database)
+      @http = http_client
+      @admin_core = EdgebaseAdmin::GeneratedAdminApi.new(http_client)
+      @database = database
+    end
+
+    # Execute a SQL query. Use ? placeholders for bind parameters.
+    def exec(query, params = nil)
+      body = { "query" => query }
+      body["params"] = params if params
+      res = @admin_core.execute_d1_query(@database, body)
+      res["results"] || []
+    end
+
+    alias query exec
+  end
+end

data/lib/edgebase_admin/functions_client.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module EdgebaseAdmin
+  class FunctionsClient
+    def initialize(http_client)
+      @http = http_client
+    end
+
+    def call(path, method: "POST", body: nil, query: nil)
+      normalized_path = "/functions/#{path.sub(%r{^/}, "")}"
+
+      case method.to_s.upcase
+      when "GET"
+        @http.get(normalized_path, params: query)
+      when "PUT"
+        @http.put(normalized_path, body)
+      when "PATCH"
+        @http.patch(normalized_path, body)
+      when "DELETE"
+        @http.delete(normalized_path)
+      else
+        @http.post(normalized_path, body)
+      end
+    end
+
+    def get(path, query: nil)
+      call(path, method: "GET", query: query)
+    end
+
+    def post(path, body = nil)
+      call(path, method: "POST", body: body)
+    end
+
+    def put(path, body = nil)
+      call(path, method: "PUT", body: body)
+    end
+
+    def patch(path, body = nil)
+      call(path, method: "PATCH", body: body)
+    end
+
+    def delete(path)
+      call(path, method: "DELETE")
+    end
+  end
+end