parse-stack-next 5.3.0 → 5.4.0

data/examples/live_query_listener.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Live Query Listener for parse-stack-next
+#
+# An interactive console listener — like a tail / `rails console` that just
+# prints: it logs in as a user, opens a LiveQuery subscription scoped to that
+# user's session token, and prints every event (create / update / delete /
+# enter / leave) until you press Ctrl-C.
+#
+# Because the subscription carries the user's `sessionToken`, Parse Server
+# enforces ACLs on the live stream too: you only receive events for objects
+# that user is allowed to read — "whatever the user can hear." Swap in a
+# master-key subscription (use_master_key: true) to hear everything.
+#
+# Prerequisite: the `Post` class must exist on the server (run
+# examples/basic_server.rb first, which provisions it). You also need a Parse
+# Server with the LiveQuery websocket server enabled for the Post class.
+#
+# Run it, then in another terminal create/update/destroy Posts (e.g. via
+# examples/basic_client.rb or the dashboard) and watch them stream in:
+#   export PARSE_SERVER_URL=http://localhost:1337/parse
+#   export PARSE_APP_ID=... PARSE_REST_KEY=...
+#   export PARSE_LIVE_QUERY_URL=ws://localhost:1337/parse   # ws:// or wss://
+#   ruby examples/live_query_listener.rb
+
+require "parse-stack-next"
+require "parse/live_query"
+
+# ---------------------------------------------------------------------------
+# 1. Configure the REST client + the LiveQuery websocket client
+# ---------------------------------------------------------------------------
+Parse.setup(
+  server_url: ENV.fetch("PARSE_SERVER_URL", "http://localhost:1337/parse"),
+  app_id:     ENV.fetch("PARSE_APP_ID"),
+  api_key:    ENV.fetch("PARSE_REST_KEY"),
+  master_key: nil,            # a plain client — the session token does the scoping
+  logging:    false,
+)
+
+Parse.live_query_enabled = true
+Parse::LiveQuery.configure do |config|
+  config.url            = ENV.fetch("PARSE_LIVE_QUERY_URL", "ws://localhost:1337/parse")
+  config.application_id = ENV.fetch("PARSE_APP_ID")
+  config.client_key     = ENV.fetch("PARSE_REST_KEY")
+end
+
+class Post < Parse::Object
+  property :title, :string
+  property :body, :string
+end
+
+# ---------------------------------------------------------------------------
+# 2. Authenticate (so the subscription is ACL-scoped to this user)
+# ---------------------------------------------------------------------------
+USERNAME = ENV.fetch("PARSE_USERNAME", "ada")
+PASSWORD = ENV.fetch("PARSE_PASSWORD", "p4ssw0rd!")
+
+user = Parse::User.login(USERNAME, PASSWORD) ||
+       Parse::User.signup(USERNAME, PASSWORD, "ada@example.com")
+puts "Listening as #{user.username} (#{user.id}) — only Posts this user can read.\n\n"
+
+# ---------------------------------------------------------------------------
+# 3. Open the subscription + register handlers
+# ---------------------------------------------------------------------------
+def stamp = Time.now.strftime("%H:%M:%S")
+
+# `where:` narrows the live query (omit it to hear every readable Post);
+# `session_token:` is what makes Parse Server apply this user's ACL to the
+# stream. Use `use_master_key: true` instead to listen to everything.
+subscription = Post.subscribe(
+  where: {},                          # e.g. { :title.exists => true }
+  session_token: user.session_token,
+)
+
+subscription.on(:subscribe)   { puts "[#{stamp}] subscribed — waiting for events…" }
+subscription.on(:create)      { |post|        puts "[#{stamp}] CREATE  #{post.id}  #{post.title.inspect}" }
+subscription.on(:update)      { |post, _orig| puts "[#{stamp}] UPDATE  #{post.id}  #{post.title.inspect}" }
+subscription.on(:delete)      { |post|        puts "[#{stamp}] DELETE  #{post.id}" }
+subscription.on(:enter)       { |post, _orig| puts "[#{stamp}] ENTER   #{post.id}  (now matches query)" }
+subscription.on(:leave)       { |post, _orig| puts "[#{stamp}] LEAVE   #{post.id}  (no longer matches)" }
+subscription.on(:error)       { |err|         warn "[#{stamp}] ERROR   #{err}" }
+
+# ---------------------------------------------------------------------------
+# 4. Block and print until Ctrl-C
+# ---------------------------------------------------------------------------
+running = true
+trap("INT") do
+  running = false               # keep the handler tiny — just flip the flag
+end
+
+puts "Press Ctrl-C to stop.\n\n"
+sleep 0.2 while running         # events arrive on the websocket thread
+
+puts "\nStopping…"
+subscription.unsubscribe
+Parse::LiveQuery.reset!         # closes the websocket connection
+puts "Done."

data/examples/rag_chatbot.rb

@@ -0,0 +1,221 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# RAG Chatbot Example for parse-stack-next
+#
+# A retrieval-augmented-generation (RAG) chatbot in a single file:
+#
+#   1. Store documents in Parse; the SDK manages their embeddings on save.
+#   2. Retrieve the most relevant passages for a question with the
+#      `semantic_search` agent tool.
+#   3. Hand those passages to an LLM to write the answer.
+#
+# The SDK owns the **R** (retrieval) and the embedding lifecycle. The **G**
+# (generation) is a thin add-in over the OpenAI or Anthropic HTTP API, shown
+# here with zero extra gems (`net/http` only).
+#
+# Retrieval (`Parse::Retrieval` / `semantic_search`) shipped in v5.2; managed
+# `embed` and the embeddings provider registry shipped in v5.1. Vector search
+# runs against MongoDB Atlas (`$vectorSearch`), so point the SDK at an
+# Atlas-backed Parse Server / Mongo URI.
+#
+# Run it:
+#   export OPENAI_API_KEY=sk-...          # embeddings + (optionally) generation
+#   export ANTHROPIC_API_KEY=sk-ant-...   # if using the Anthropic backend
+#   export PARSE_SERVER_URL=http://localhost:1337/parse
+#   export PARSE_APP_ID=... PARSE_REST_KEY=... PARSE_MASTER_KEY=...
+#   ruby examples/rag_chatbot.rb
+
+require "parse-stack-next"
+require "net/http"
+require "json"
+
+# ---------------------------------------------------------------------------
+# 1. Embedding provider + Parse connection
+# ---------------------------------------------------------------------------
+
+# text-embedding-3-small is 1536-dim. Register it under :openai so the model's
+# :vector property can resolve it by name at save / query time.
+Parse::Embeddings.register(
+  :openai,
+  Parse::Embeddings::OpenAI.new(api_key: ENV.fetch("OPENAI_API_KEY")),
+)
+
+Parse.setup(
+  server_url: ENV.fetch("PARSE_SERVER_URL", "http://localhost:1337/parse"),
+  app_id:     ENV.fetch("PARSE_APP_ID"),
+  api_key:    ENV.fetch("PARSE_REST_KEY"),
+  master_key: ENV.fetch("PARSE_MASTER_KEY"),
+)
+
+# ---------------------------------------------------------------------------
+# 2. The model
+# ---------------------------------------------------------------------------
+#
+# `embed` declares a MANAGED embedding: list the source fields, name the
+# :vector property they feed, and the SDK recomputes the vector on `save`
+# whenever those fields change (digest-tracked, so a no-op save makes zero
+# provider calls). You never assign `embedding` yourself — it is
+# write-protected. Set title/body and save.
+#
+# `agent_searchable` opts the class into the `semantic_search` agent tool and
+# declares which fields an agent may filter on.
+class KnowledgeArticle < Parse::Object
+  property :title, :string
+  property :body, :string
+  property :category, :string
+
+  property :embedding, :vector, dimensions: 1536, provider: :openai
+
+  # title + body feed :embedding, recomputed on save.
+  embed :title, :body, into: :embedding
+
+  # Opt into semantic_search; allow filtering on :category.
+  agent_searchable field: :embedding, filter_fields: %i[category]
+
+  # Declare the Atlas $vectorSearch index that retrieval needs.
+  mongo_search_index "knowledge_embedding",
+                     { fields: [{ type: "vector", path: "embedding",
+                                  numDimensions: 1536, similarity: "cosine" }] },
+                     type: "vectorSearch"
+end
+
+# ---------------------------------------------------------------------------
+# 3. The LLM generation add-in (NOT part of the SDK)
+# ---------------------------------------------------------------------------
+#
+# ~15 lines of HTTP per backend. Both take the retrieved chunks as context and
+# return an answer grounded in them.
+module ChatAnswerer
+  PROMPT = <<~SYS
+    You are a support assistant. Answer ONLY from the context below.
+    If the context does not contain the answer, say you don't know.
+  SYS
+
+  module_function
+
+  def context(chunks)
+    chunks.map { |c| "- #{c[:content]}" }.join("\n")
+  end
+
+  # --- OpenAI backend ---
+  def openai(question, chunks, model: "gpt-4o-mini")
+    post("https://api.openai.com/v1/chat/completions",
+         { "Authorization" => "Bearer #{ENV.fetch('OPENAI_API_KEY')}" },
+         { model: model,
+           messages: [
+             { role: "system", content: PROMPT },
+             { role: "user",
+               content: "Context:\n#{context(chunks)}\n\nQuestion: #{question}" },
+           ] })
+      .dig("choices", 0, "message", "content")
+  end
+
+  # --- Anthropic backend ---
+  def anthropic(question, chunks, model: "claude-opus-4-8")
+    post("https://api.anthropic.com/v1/messages",
+         { "x-api-key"         => ENV.fetch("ANTHROPIC_API_KEY"),
+           "anthropic-version" => "2023-06-01" },
+         { model: model, max_tokens: 1024, system: PROMPT,
+           messages: [
+             { role: "user",
+               content: "Context:\n#{context(chunks)}\n\nQuestion: #{question}" },
+           ] })
+      .dig("content", 0, "text")
+  end
+
+  def post(url, headers, body)
+    uri = URI(url)
+    req = Net::HTTP::Post.new(uri, { "Content-Type" => "application/json" }.merge(headers))
+    req.body = JSON.generate(body)
+    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
+    JSON.parse(res.body)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# 4. Retrieval helper
+# ---------------------------------------------------------------------------
+#
+# An unscoped Parse::Agent (no session_token: / acl_user: / acl_role:) runs in
+# master posture using the master key already on the default client from
+# Parse.setup — there is NO `master_key:` constructor argument.
+#
+# To scope retrieval to a signed-in user (so the bot only ever sees documents
+# that user may read), construct it as:
+#     Parse::Agent.new(session_token: user.session_token)
+#
+# `execute(:semantic_search, ...)` returns
+#   { success:, data: { chunks:, documents:, count: } }.
+def retrieve(agent, question, k: 4)
+  result = agent.execute(:semantic_search,
+                         class_name: "KnowledgeArticle",
+                         query: question,
+                         k: k)
+  raise result[:error].to_s unless result[:success]
+
+  # Each chunk: { id:, score:, content:, metadata: { object_id:, ... } }.
+  # The parent record lives once in data[:documents], keyed by objectId.
+  result[:data][:chunks]
+end
+
+# ---------------------------------------------------------------------------
+# 5. Seed a corpus + chat loop (runs when executed directly)
+# ---------------------------------------------------------------------------
+
+CORPUS = [
+  { title: "Resetting your password",
+    body: "Open Settings, choose Security, then Reset Password. A link is emailed to you.",
+    category: "account" },
+  { title: "Exporting your data",
+    body: "Use Settings > Export to download a ZIP of all your documents as JSON.",
+    category: "data" },
+  { title: "Billing cycles",
+    body: "Plans renew monthly on the date you subscribed. Cancel anytime before renewal.",
+    category: "billing" },
+].freeze
+
+# Bulk back-fill / precompute outside the managed-save path: call the provider
+# directly. `embed_text_batched` splits into the provider's recommended batch
+# size (OpenAI: 100) and returns one vector per string, in order. (Not used by
+# the demo below — `save` handles embedding — but shown for completeness.)
+def precompute_vectors(texts)
+  provider = Parse::Embeddings.provider(:openai)
+  provider.embed_text_batched(texts, input_type: :search_document)
+end
+
+def seed_corpus!
+  # $vectorSearch needs an Atlas vector index on `embedding`, or retrieval
+  # raises IndexNotResolved. The model declares it; apply it once. This uses
+  # the mongo-direct writer (requires Parse::MongoDB configured against Atlas)
+  # — or create the same index in the Atlas UI.
+  KnowledgeArticle.apply_search_indexes!(wait: true)
+
+  # Managed embedding means ingestion is just `save`: each save that changes a
+  # source field makes one embedding call; unchanged re-saves make none.
+  CORPUS.each { |attrs| KnowledgeArticle.new(attrs).save }
+end
+
+def chat_loop(backend: :anthropic)
+  # Master posture (reads everything). Emits a one-time master-key warning to
+  # stderr; silence it with Parse::Agent.suppress_master_key_warning = true.
+  agent = Parse::Agent.new
+
+  puts "Ask a question (Ctrl-D to quit):"
+  while (question = $stdin.gets&.strip)
+    next if question.empty?
+
+    chunks = retrieve(agent, question)
+    answer = ChatAnswerer.public_send(backend, question, chunks)
+
+    puts "\n#{answer}\n"
+    sources = chunks.map { |c| c.dig(:metadata, :object_id) }.uniq.join(", ")
+    puts "  (sources: #{sources})\n\n"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  seed_corpus!
+  # Pick :openai or :anthropic for the generation step.
+  chat_loop(backend: :anthropic)
+end

data/examples/webhook_server.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Cloud Code Webhooks for parse-stack-next
+#
+# Webhooks are how a Ruby backend runs SERVER-SIDE trigger logic. Without them,
+# a Parse::Object's ActiveModel callbacks (before_save, after_create, …) run
+# ONLY in the Ruby process that initiated the save. A write that comes from a
+# JS/Swift/REST client — or the Parse Dashboard — never touches your Ruby code,
+# so that logic is silently skipped server-side.
+#
+# Registering a webhook flips that: Parse Server calls back into this Ruby app
+# on the matching trigger, and your ActiveModel callbacks + webhook blocks run
+# for EVERY client, not just Ruby ones.
+#
+# This file is a Rack app. Mount it (config.ru):
+#
+#   require_relative "examples/webhook_server"
+#   run Parse::Webhooks
+#
+# and point Parse Server's `webhookKey` at the same value as Parse::Webhooks.key.
+#
+# See docs/webhooks_guide.md for the full picture (trigger types, the
+# ActiveModel↔Parse hook relationship, latency, and replay protection).
+
+require "parse-stack-next"
+
+# ---------------------------------------------------------------------------
+# 1. Configure the (master-key) client + the webhook key
+# ---------------------------------------------------------------------------
+Parse.setup(
+  server_url: ENV.fetch("PARSE_SERVER_URL", "http://localhost:1337/parse"),
+  app_id:     ENV.fetch("PARSE_APP_ID"),
+  api_key:    ENV.fetch("PARSE_REST_KEY"),
+  master_key: ENV.fetch("PARSE_MASTER_KEY"),
+)
+
+# Shared secret Parse Server sends as `X-Parse-Webhook-Key`. Set the same value
+# in Parse Server's `webhookKey` option. Requests without it are rejected.
+Parse::Webhooks.key = ENV.fetch("PARSE_WEBHOOK_KEY")
+
+# Optional: server-initiated replay/freshness protection (see the guide). The
+# body+request-id dedup is always on; an HMAC signing secret adds freshness
+# verification of X-Parse-Webhook-Timestamp / X-Parse-Webhook-Signature.
+Parse::Webhooks::ReplayProtection.signing_secret = ENV["PARSE_WEBHOOK_SIGNING_SECRET"]
+
+# ---------------------------------------------------------------------------
+# 2. A model with both ActiveModel callbacks AND webhook blocks
+# ---------------------------------------------------------------------------
+class Post < Parse::Object
+  property :title, :string, required: true
+  property :slug, :string
+  property :published, :boolean, default: false
+
+  # ActiveModel callbacks. For a Ruby-initiated save these run locally; for a
+  # NON-Ruby client they run here only if a beforeSave/afterSave webhook is
+  # registered for Post. Registering beforeSave enables BOTH before_save and
+  # before_create; afterSave enables both after_save and after_create.
+  before_save  :normalize_slug
+  before_create { self.published = false } # created drafts start unpublished
+  after_create :enqueue_welcome           # see note on afterSave below
+
+  def normalize_slug
+    self.slug = title.to_s.downcase.strip.gsub(/[^a-z0-9]+/, "-") if title_changed?
+  end
+
+  def enqueue_welcome
+    # AFTER-SAVE BEST PRACTICE: enqueue, don't execute. Parse Server blocks the
+    # client's write until this webhook returns — even though afterSave's return
+    # is a no-op — so long work here adds latency to every save. And do NOT save
+    # another object here if you can avoid it: each cascading save fires more
+    # webhooks (a latency cascade). Hand off to a background job instead.
+    # BackgroundJobs.enqueue(:index_post, id)
+  end
+end
+
+Post.auto_upgrade!
+
+# ---------------------------------------------------------------------------
+# 3. Webhook blocks (optional) — server-side logic without a Ruby model callback
+# ---------------------------------------------------------------------------
+# A block runs in the scope of a Parse::Webhooks::Payload. A beforeSave block
+# returns `parse_object` (the SDK turns it into the changes Parse Server wants);
+# returning `false` halts the save.
+class Post
+  webhook :before_save do
+    # `parse_object` is the incoming object; mutate it, then return it.
+    parse_object
+  end
+
+  # afterSave/afterDelete blocks may register more than one handler.
+  webhook :after_save do
+    # keep this short or enqueue — see enqueue_welcome above.
+    true
+  end
+end
+
+# NOTE: there is no `webhook :before_create` / `:after_create`. Parse Server has
+# no such trigger — register beforeSave/afterSave and your create callbacks fire
+# within them for new objects. Asking for a create webhook raises with guidance.
+
+# ---------------------------------------------------------------------------
+# 4. Register the webhooks with Parse Server (run once at deploy, needs master key)
+# ---------------------------------------------------------------------------
+# `endpoint` is the public HTTPS URL where THIS Rack app is reachable.
+if ENV["PARSE_WEBHOOK_ENDPOINT"]
+  endpoint = ENV.fetch("PARSE_WEBHOOK_ENDPOINT") # e.g. https://hooks.example.com/webhooks
+  Parse::Webhooks.register_functions!(endpoint)
+  Parse::Webhooks.register_triggers!(endpoint)
+  puts "Registered webhooks at #{endpoint}"
+end