lingara-apps 0.1.0.pre.alpha.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8a61747c3cc110da1bb7c6c8a740469f1e7c012e8fa9b10bf4c0f39bbc00434e
+  data.tar.gz: 2cb2dafce84916289cd6c126781491c87204643845ec55c4285c17dc364b4756
+SHA512:
+  metadata.gz: 74dd035b96142df84a02710383c548ffbefcf3f7993656870fa3776f437da71de16ce43a8babfaa1a3807804a6ec1c5080fce30b92c83e80843eb7159d87729b
+  data.tar.gz: a37f11e1c5fcc280987ebcfeffc3a1a485d9aec224ea0410d580d618341082aa308186a90dce2fb7eb52a9e91216ca55f257972889810f21eef8e0bd97633a7c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spinning Cat Studios
+
+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,123 @@
+# lingara-apps (Ruby)
+
+The Ruby kit for building a [Lingara](https://getlingara.com) app: a server
+that answers Lingara's two signed requests, `app.render` and `app.action`,
+with a card. The kit verifies each request, decodes it, calls your block,
+checks the card it returns against Lingara's card rules and sends it. Its
+one runtime dependency is the
+[`lingara` gem](https://github.com/Spinning-Cat-Studios/lingara_api_clients/tree/main/ruby),
+whose webhook verifier checks every signature; the adapter speaks the Rack
+protocol without depending on the `rack` gem.
+
+## Install
+
+```sh
+gem install lingara-apps
+```
+
+or, in a Gemfile, `gem "lingara-apps"`. **Ruby 3.3 or newer**, the library's
+floor. While both are pre-releases, add `--pre` (or name the version).
+
+## Quick start
+
+```ruby
+# config.ru
+require "lingara/apps"
+
+# The app's signing secret, lgr_whsec_…, or an Array of both during a
+# rotation. A malformed secret raises ArgumentError here, at startup.
+app = Lingara::Apps::App.new(secret: ENV.fetch("LINGARA_APP_SECRET"))
+
+app.render do |request|
+  Lingara::Apps.card
+    .heading("Today", 1)
+    .term(word: "雨", reading: "yǔ", gloss: "rain", lang: "zh")
+    .button("Next", "next")
+    .build
+end
+
+app.action("next") do |request|
+  card = Lingara::Apps.card.heading("Nice work", 1).build
+  Lingara::Apps.reply(card).tutor_note("The learner finished today's word.")
+end
+
+run Lingara::Apps::RackApp.new(app)
+```
+
+`Lingara::Apps::RackApp.new(app)` is a Rack endpoint (`#call(env)`), so it
+runs under Puma, Falcon or `rackup`, and mounts in Rails
+(`mount Lingara::Apps::RackApp.new(app), at: "/lingara"`) or Sinatra. It
+reads `rack.input` itself, as raw bytes, before anything parses it: mount it
+where no middleware has already read or decoded the body (no JSON
+body-parsing middleware in front of it), because the signature covers the
+exact bytes Lingara sent.
+
+### What your blocks receive
+
+`Lingara::Apps::AppRenderRequest` and `AppActionRequest` carry `id` (the
+`lgr_msg_…` request id), `install_id`, `subject` (the `lgr_sub_…` value your
+app's events carry too: key per-learner state on it), `slot`, `locale` and
+`context`, and an action adds `action_id` (the button's `action`) and
+`card_etag`. `card_etag` is opaque: it tells two presses of one card apart,
+and nothing more.
+
+`context` holds the slices the learner agreed to share, each an arm of the
+sealed `Lingara::Apps::ContextSlice`: match on `ContextSliceLanguages`,
+`ContextSlicePlanSummary`, `ContextSliceReviewDue` or
+`ContextSliceTutorTopic`, for example
+`in Lingara::Apps::ContextSlicePlanSummary(plan_id:)`. A kind this kit does
+not know yet is skipped and logged, never an error. The context is read-only
+data. To read the plan behind a `plan_summary` slice, call the library's
+`client.get_lesson_plan(plan_id)`. For a private app, that is your app's own
+client-credentials client (`Lingara::Client.new(client_id:, client_secret:)`),
+which speaks for its owner; for any other learner it needs that learner's
+own OAuth token.
+
+### What your blocks return
+
+A `Lingara::Apps::Card` (from `Lingara::Apps.card…build`), or
+`Lingara::Apps.reply(card).tutor_note(text)` for a card with a tutor note:
+plain text, at most 280 characters, that Lingara's tutor may use. The kit
+runs `Lingara::Apps.validate_reply` on every reply. A block that raises, or a
+reply that breaks a card rule or encodes to more than 32 768 bytes, is
+answered `500 {"error":"handler_failed"}` and logged through the `lingara`
+library's logger (the operation, the install id and the reason, never the
+body, a secret or a signature). Pass `logger:` (anything with `#warn`, such
+as `Rails.logger`) to use your own.
+
+## The builders refuse; they never cut
+
+Lingara cuts, strips or drops whatever in a card breaks its rules. The kit
+refuses instead, so that never happens to a card you built:
+`CardBuilder#build` raises `Lingara::Apps::CardLimitError`, whose `reason`
+names the rule (`:text_length`, `:list_items`, `:link` and so on). The limits
+are constants in `Lingara::Apps::Limits`. Characters are Unicode scalar
+values (`String#length` on UTF-8). `Lingara::Apps.truncate(text, limit)` gives
+a string the clamp's shape (its first `limit − 1` characters and `…`) when
+you want one; the kit never calls it for you.
+
+`Lingara::Apps.manifest` builds the manifest you upload in the console;
+`build` raises `Lingara::Apps::ManifestError`, whose `rule` names the rule it
+breaks, and `to_json` writes `manifest.json`. A bare `name("…")` is the name
+in the default locale.
+
+## Things to know
+
+- **The user agent.** Lingara's requests carry
+  `user-agent: Lingara-Apps/1 (+https://getlingara.com/docs/apps/)`, so you
+  can recognise them in your logs. It is unsigned, so never use it as a gate:
+  the signature is the gate.
+- **Time budgets.** Lingara waits 3 s for a render and 5 s for an action, and
+  never retries. A slow render shows the learner a stale or fallback card.
+  The kit enforces no timeout of its own.
+- **Actions may arrive twice.** The kit stores nothing, so make each action
+  block safe to run twice.
+- **Events are the library's.** `app.installed`, `app.uninstalled` and the
+  other events reach a webhook endpoint, verified by the library's own
+  `Lingara::Events::Webhook#verify` and its event types, not by this kit.
+
+## The contract
+
+Every Lingara app kit keeps one contract, checked by one conformance host
+against a fixture app in each language:
+[`../conformance/CONTRACT.md`](../conformance/CONTRACT.md).

data/lib/lingara/apps/app.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lingara
+  module Apps
+    # An app (ADR 30.9.26am D4): its verifier, built once, its render
+    # function and its action functions, and the framework-neutral core every
+    # adapter calls. The signature check is the library's
+    # (Lingara::Events::Webhook#verify_signature), never the kit's own.
+    #
+    #   app = Lingara::Apps::App.new(secret: ENV.fetch("LINGARA_APP_SECRET"))
+    #   app.render { |request| Lingara::Apps.card.heading(request.slot).build }
+    #   app.action("next") { |request| ... }
+    #
+    # A function returns a Card, or Lingara::Apps.reply(card).tutor_note(text).
+    class App
+      JSON_TYPE = {"content-type" => "application/json"}.freeze
+      BAD_REQUEST = [400, JSON_TYPE, '{"error":"bad_request"}'].freeze
+      HANDLER_FAILED = [500, JSON_TYPE, '{"error":"handler_failed"}'].freeze
+
+      # Each request message the core answers, and how. A unit test holds
+      # its keys to the generated Operations::REQUESTS.
+      DISPATCH = {
+        Operations::RENDER => :render_function,
+        Operations::ACTION => :action_function
+      }.freeze
+
+      attr_reader :webhook
+
+      # +secret+ is the app's signing secret (lgr_whsec_…), or an Array of
+      # them during a rotation. The library's Webhook is built here, so a
+      # malformed secret is ArgumentError at startup, not on a request.
+      # +logger+ is any object with #warn; the library's own by default.
+      def initialize(secret:, logger: Lingara::DefaultLogger.new)
+        @webhook = Lingara::Events::Webhook.new(secret)
+        @logger = logger
+        @render = nil
+        @actions = {}
+      end
+
+      # Registers the render function: it receives an AppRenderRequest.
+      def render(&block)
+        raise ArgumentError, "render needs a block" unless block
+        @render = block
+        self
+      end
+
+      # Registers the function for one button +action+: it receives an
+      # AppActionRequest whose action_id is +id+.
+      def action(id, &block)
+        raise ArgumentError, "action needs a block" unless block
+        @actions[id.to_s] = block
+        self
+      end
+
+      # One request, start to finish (AK1–AK4): [status, headers, body].
+      # +read+ is called once with the most bytes to read and returns the
+      # body read so far, a String.
+      def handle(method, headers, read)
+        return [405, {}, ""] unless method == "POST"
+        body = read.call(Limits::REQUEST_MAX_BYTES + 1).to_s
+        return [413, {}, ""] if body.bytesize > Limits::REQUEST_MAX_BYTES
+        begin
+          @webhook.verify_signature(body, headers)
+        rescue Lingara::Events::VerificationError
+          return [401, {}, ""]
+        end
+        request = Decoder.new(@logger).decode(body)
+        fn = request && send(DISPATCH.fetch(request.type), request)
+        fn ? answer(request, fn) : BAD_REQUEST
+      end
+
+      private
+
+      # No render function registered is the app's failure, so a 500.
+      def render_function(_request)
+        @render || ->(_) { raise "no render function is registered" }
+      end
+
+      def action_function(request)
+        @actions[request.action_id]
+      end
+
+      def answer(request, fn)
+        result = fn.call(request)
+        wire = result.is_a?(Reply) ? result.to_wire : {"card" => Apps.card_wire(result)}
+        [200, JSON_TYPE, Limits.validate_reply(wire)]
+      rescue => e
+        log(request, reason(e))
+        HANDLER_FAILED
+      end
+
+      def reason(error)
+        return "reply refused: #{error.reason}" if error.is_a?(CardLimitError)
+        "raised #{error.class}: #{error.message}"
+      end
+
+      # The operation, the install and the reason: never the body, a secret
+      # or a signature.
+      def log(request, reason)
+        @logger.warn("lingara-apps: #{request.type} for install #{request.install_id} failed: #{reason}")
+      end
+    end
+
+    # The request, decoded leniently into the generated type: an unknown
+    # field is ignored, and a context slice of an unknown kind is skipped
+    # with a log line, element by element, before the union is read (AK2).
+    class Decoder
+      # The members every request carries as strings, and an action's two.
+      STRINGS = %w[id install_id subject locale].freeze
+      ACTION_STRINGS = %w[action_id card_etag].freeze
+
+      def initialize(logger)
+        @logger = logger
+      end
+
+      # The generated request, or nil (a 400).
+      def decode(body)
+        raw = parse(body)
+        return nil unless raw.is_a?(Hash) && App::DISPATCH.key?(raw["type"])
+        return nil unless ManifestRules::SLOT_NAMES.include?(raw["slot"]) && strings?(raw)
+        context = context(raw["context"])
+        return nil unless context
+        request = Apps.const_get(Operations::REQUESTS.fetch(raw["type"])).build_from_hash(raw.merge("context" => []))
+        request.context = context
+        request
+      rescue
+        nil
+      end
+
+      private
+
+      def strings?(raw)
+        names = (raw["type"] == Operations::ACTION) ? STRINGS + ACTION_STRINGS : STRINGS
+        names.all? { |name| raw[name].is_a?(String) }
+      end
+
+      def parse(body)
+        text = body.dup.force_encoding(Encoding::UTF_8)
+        text.valid_encoding? ? JSON.parse(text) : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def context(raw)
+        return nil unless raw.is_a?(Array)
+        raw.each_with_object([]) do |element, slices|
+          raise ArgumentError, "a context slice is not an object" unless element.is_a?(Hash) && element["kind"].is_a?(String)
+          slice = ContextSlice.decode(element)
+          slice ? slices << slice : skip(element["kind"])
+        end
+      end
+
+      def skip(kind)
+        @logger.warn("lingara-apps: skipped a context slice of unknown kind #{kind[0, 64].inspect}")
+      end
+    end
+  end
+end

data/lib/lingara/apps/card.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Lingara
+  module Apps
+    # List items for CardBuilder#list: ListItemText and ListItemTerm.
+    module Item
+      module_function
+
+      def text(text, lang: nil)
+        ListItemText.new(text: text, lang: lang)
+      end
+
+      def term(word:, reading: nil, gloss: nil, lang: nil)
+        ListItemTerm.new(word: word, reading: reading, gloss: gloss, lang: lang)
+      end
+    end
+
+    # A fluent card (ADR 30.9.26am D5): one method per element, each taking
+    # its generated arm's closed member set, and #build checks the card
+    # rules. A kit refuses what the relay would clamp, so the clamp never
+    # fires on a kit-built card.
+    #
+    #   Lingara::Apps.card.heading("Today").term(word: "雨", reading: "yǔ").button("Next", "next").build
+    class CardBuilder
+      def initialize
+        @elements = []
+      end
+
+      def heading(text, level = 1)
+        push(CardElementHeading.new(text: text, level: level))
+      end
+
+      def text(text, lang: nil)
+        push(CardElementText.new(text: text, lang: lang))
+      end
+
+      def term(word:, reading: nil, gloss: nil, lang: nil)
+        push(CardElementTerm.new(word: word, reading: reading, gloss: gloss, lang: lang))
+      end
+
+      # +items+ are Item.text and Item.term values.
+      def list(items)
+        push(CardElementList.new(items: items.to_a.dup.freeze))
+      end
+
+      def progress(value, label)
+        push(CardElementProgress.new(value: value, label: label))
+      end
+
+      def divider
+        push(CardElementDivider.new)
+      end
+
+      # +action+ comes back as the request's action_id; +style+ is a
+      # ButtonStyle value ("primary" or "secondary").
+      def button(label, action, style: nil)
+        push(CardElementButton.new(label: label, action: action, style: style))
+      end
+
+      def link(label, url)
+        push(CardElementLink.new(label: label, url: url))
+      end
+
+      # The generated Card, or CardLimitError naming the first card rule it
+      # breaks.
+      def build
+        card = Card.new(elements: @elements.dup.freeze)
+        Limits.check_card(Apps.card_wire(card))
+        card
+      end
+
+      private
+
+      def push(element)
+        @elements << element
+        self
+      end
+    end
+
+    # A card and, optionally, a tutor note: what a render or action function
+    # may return instead of a bare card.
+    class Reply
+      attr_reader :card
+
+      def initialize(card)
+        raise ArgumentError, "a reply carries a Lingara::Apps::Card" unless card.is_a?(Card)
+        @card = card
+        @tutor_note = nil
+      end
+
+      # Plain text, at most 280 characters once `\n` becomes a space and the
+      # ends are trimmed; CardLimitError otherwise.
+      def tutor_note(text = nil)
+        return @tutor_note if text.nil?
+        Limits.check_tutor_note(text)
+        @tutor_note = text
+        self
+      end
+
+      # The wire form, {card, tutor_note?}: an absent note is omitted.
+      def to_wire
+        wire = {"card" => Apps.card_wire(@card)}
+        wire["tutor_note"] = @tutor_note unless @tutor_note.nil?
+        wire
+      end
+    end
+
+    module_function
+
+    # Starts a card.
+    def card
+      CardBuilder.new
+    end
+
+    # The list-item constructors: `Lingara::Apps.item.text("one")`.
+    def item
+      Item
+    end
+
+    # Wraps a built card so a tutor note can ride with it.
+    def reply(card)
+      Reply.new(card)
+    end
+
+    # A generated Card's wire form, {elements: [...]}, each arm in its own.
+    def card_wire(card)
+      {"elements" => card.elements.map { |e| e.respond_to?(:to_wire) ? e.to_wire : e }}
+    end
+
+    # The relay's cut, when asked for: Limits.truncate.
+    def truncate(text, limit)
+      Limits.truncate(text, limit)
+    end
+
+    # Limits.validate_reply: the bytes to send, or CardLimitError.
+    def validate_reply(reply)
+      Limits.validate_reply(reply)
+    end
+  end
+end