lingara 0.2.0.pre.alpha.4 → 0.2.0.pre.alpha.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e1d7800b570c108fac871dee55f078c590ebe11c708c5a9e991013b6a0a91a8
-  data.tar.gz: 4e6fb8dbee4b626ec0027122306a1d69c878080624fdb02cfbfd77fa18b002c9
+  metadata.gz: 5e943622393135dc22889e58f20576f09b77e025d2cc932d5bc7b29e474106e7
+  data.tar.gz: 716d6f0423e4b090b1501a1a8a822dc8a9e288a9e584649be1801d781d275dc9
 SHA512:
-  metadata.gz: 88939b0e78a2b3e05aeeec1c961ffe39c24f28c7edcc99e0815051d2188784904143790fb183f986e0d9c0eebcbd059082b34f8c0e12877203b16ca7a9980c0b
-  data.tar.gz: 317b65dc02a825c0f15f08f3aa43b0fb53f2afa642e725be2e8f38f494a6d0fb220818adf5a5838d83c6f3364c74b9d0c0af4f541e9dd19c136f2174abbec4bd
+  metadata.gz: 7f29623a41324b9824a178f4aa563d7e38688a28a4754d492dc270ab6417c5d908c36c3e8c3f7a57f4c4e80ec176c1100a86466152438bb48aa53120973557c0
+  data.tar.gz: abca4a29e74e84236a5e933868df3dd47df14a8952572db0df11cd263cdb7e12e7a6acfc9f2f2570d8736a1347da2061de672b2b8284224364b2ac80abf4da9e

data/README.md

@@ -228,6 +228,96 @@ For higher-level helpers on your server, see the
 [Lingara embed server kits](https://github.com/Spinning-Cat-Studios/lingara_embeddable_sdk)
 (the `lingara-embed` gem).
 
+## Canvases
+
+The canvas operations (`canvas:read`, `canvas:write`) live on one group,
+`client.canvases`, which uses the client's own token, retries, version pin
+and errors. Each returns a `Lingara::Response`:
+
+```ruby
+canvases = client.canvases
+page = canvases.list_canvases(status: "live", kinds: ["webhook"], limit: 20).value  # a CanvasPage
+canvas = canvases.create_canvas({name: "Hooks", recipe: "lesson_plan_ready", definition: definition}).value
+canvas = canvases.get_canvas(canvas.id).value          # draft and active inline
+canvases.rename_canvas(canvas.id, {name: "Lesson plan webhook"})
+canvases.save_canvas_draft(canvas.id, {definition: definition, draft_version: canvas.draft.draft_version})
+canvases.activate_canvas(canvas.id, {draft_version: 4, outcome: "complete", objects: {"n1" => {id: object_id}}})
+dry_run = canvases.dry_run_canvas_plan({ops: ops}).value  # 200 whether or not dry_run.ok
+canvases.page_canvases(kinds: ["webhook"]).each { |item| puts item.name }
+```
+
+`page_canvases(**filters)` follows `next_cursor` until a page says
+`has_more: false`, resending the filters on every page; it never sleeps and
+stops on the first error, and a page with `has_more` but no `next_cursor` is
+`TransportError` `:malformed_response`. A node's `fields` and `params` are
+open hashes, so a definition read and saved back keeps keys this library does
+not know.
+
+A stale `draft_version` is `409 canvas_conflict`, raised as
+`Lingara::ApiError` and **never retried**. Re-read with `get_canvas`, compare
+its draft with the one you sent (after a retried save it may be your own),
+take its `draft_version`, and decide; the library never merges or re-sends.
+A replayed `activate_canvas` at a `draft_version` already promoted answers
+`409 canvas_conflict` too, and writes nothing. Branch on `code`, show the
+message only as a fallback, and localise by code: the ten `canvas_*` codes are
+the contract, the text is not. A dry-run's `refused` verdict carries its
+`code` and an English `error` as data, never raised.
+
+A canvas is deleted through the platform's lifecycle routes, not this library.
+
+## Dialogues
+
+The stored-dialogue operations (`dialogues:read`, `dialogues:write`) live on
+one group, `client.dialogues`, which uses the client's own token, retries,
+version pin and errors. Each returns a `Lingara::Response`:
+
+```ruby
+dialogues = client.dialogues
+page = dialogues.list_dialogues(name: "market", limit: 20).value  # a DialoguePage
+dialogue = dialogues.create_dialogue({name: "Night market", definition: definition}).value
+dialogue = dialogues.get_dialogue(dialogue.id).value       # draft and active inline
+dialogues.rename_dialogue(dialogue.id, {name: "Night market keepers"})
+dialogues.save_dialogue_draft(dialogue.id, {definition: definition, draft_version: dialogue.draft.draft_version})
+dialogues.activate_dialogue(dialogue.id, {draft_version: 4})
+exported = dialogues.export_dialogue(dialogue.id, if_none_match: cached_etag).value
+dialogues.page_dialogues(name: "market").each { |item| puts item.name }
+```
+
+`page_dialogues(name:, limit:)` follows `next_cursor` until a page says
+`has_more: false`, resending the filters on every page; it never sleeps and
+stops on the first error, and a page with `has_more` but no `next_cursor` is
+`TransportError` `:malformed_response`. A definition is an open hash, so one
+read and saved back keeps keys this library does not know, `x-layout`
+included. A `warnings` entry is advice, never a refusal; a warning `code`
+this library's spec does not list fails to decode the `Dialogue`
+(`TransportError` `:malformed_response`) until the library is upgraded.
+
+A stale `draft_version` is `409 dialogue_conflict`, raised as
+`Lingara::ApiError` and **never retried**. Re-read with `get_dialogue`, take
+its `draft.draft_version` (or send `0` when `draft` is `nil`, which opens
+one), and decide; after a retried save the change may be your own, and the
+library never merges or re-sends. A replayed `activate_dialogue` answers
+`409 dialogue_conflict` too, and writes nothing. Branch on `code`, show the
+message only as a fallback, and localise by code: the `dialogue_*` codes are
+the contract, the text is not. `400 dialogue_invalid` and
+`400 dialogue_graph_invalid` carry `path` and `rule` on the wire, but this
+release does not surface them on `ApiError`: a tool that needs them reads the
+`400`'s body itself.
+
+`export_dialogue(id, revision:, layout:, if_none_match:)` answers a
+`Response` whose `value` is a `Lingara::ExportedDialogue::Body` (`revision`,
+`etag`, `ir_json`) or, when `if_none_match:` still matches, a
+`Lingara::ExportedDialogue::NotModified` (`revision`, `etag`): a `304` is an
+answer, never an error. Cache by `etag`: `ir_json` is the `dialogue.v1`
+document as canonical bytes, never parsed here, so store it exactly as
+received and send the `etag` back unchanged. A `304` still spends one unit of
+the rate budget. `revision:` (`"active"` or `"draft"`) and `layout:`
+(`"keep"` or `"omit"`) are sent only when given; a missing `ETag` or
+`Lingara-Dialogue-Revision` is `TransportError` `:malformed_response`.
+
+A dialogue is deleted through the platform's lifecycle routes, not this
+library.
+
 ## Errors
 
 Every failure is a `Lingara::Error`, one of four:

data/lib/lingara/canvas.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Lingara
+  # The canvas operations (ADR 16.10.26ak; scopes canvas:read and
+  # canvas:write), reached as client.canvases. The group holds no state of
+  # its own: every call goes through the client's request path, so the
+  # token, retries, version pin and errors are the client's. Each call
+  # returns a Response.
+  #
+  # A stale draft_version is 409 canvas_conflict, raised as an ApiError and
+  # never retried: re-read with get_canvas, compare its draft with yours
+  # (after a retried save it may be your own), and decide. A replayed
+  # activate_canvas answers 409 canvas_conflict too, and writes nothing.
+  # Branch on an error's code, never its localised message. A dry-run
+  # answers 200 whether or not ok is true; a refused verdict's code and
+  # English error are data. There is no delete: a canvas is deleted through
+  # the platform's lifecycle routes, not this library.
+  class Canvases
+    # Built by Client#canvases over the client's own request path.
+    def initialize(request)
+      @request = request
+    end
+
+    # One page of canvases, a CanvasPage; page_canvases walks them. The
+    # lists are sent comma-separated, one value each.
+    def list_canvases(cursor: nil, limit: nil, name: nil, status: nil, recipes: nil, kinds: nil, scopes: nil)
+      lists = {recipes: recipes, kinds: kinds, scopes: scopes}.transform_values { |list| list unless list.nil? || list.empty? }
+      @request.call("listCanvases", [], {cursor: cursor, limit: limit, name: name, status: status, **lists}, nil)
+    end
+
+    # Creates a canvas (201). The answer does not echo recipe.
+    def create_canvas(body)
+      @request.call("createCanvas", [], nil, body)
+    end
+
+    # One canvas, its draft and active revision inline.
+    def get_canvas(canvas_id)
+      @request.call("getCanvas", [canvas_id], nil, nil)
+    end
+
+    # Renames a canvas (PATCH): body is {name:}.
+    def rename_canvas(canvas_id, body)
+      @request.call("renameCanvas", [canvas_id], nil, body)
+    end
+
+    # Saves the draft (PUT): body is {definition:, draft_version:, name:}.
+    # A stale draft_version is 409 canvas_conflict, which may follow your
+    # own retried save: re-read with get_canvas and compare first.
+    def save_canvas_draft(canvas_id, body)
+      @request.call("saveCanvasDraft", [canvas_id], nil, body)
+    end
+
+    # Promotes a draft with the objects an apply made: body is
+    # {draft_version:, outcome:, objects:}.
+    def activate_canvas(canvas_id, body)
+      @request.call("activateCanvas", [canvas_id], nil, body)
+    end
+
+    # Judges a plan ({ops:}) without applying it. A plan with a refused op
+    # still answers 200, ok false.
+    def dry_run_canvas_plan(body)
+      @request.call("dryRunCanvasPlan", [], nil, body)
+    end
+
+    # Every CanvasSummary the filters match, following next_cursor until a
+    # page says has_more false, the filters resent on every page: an
+    # Enumerator that fetches lazily, or with a block, each item yielded. It
+    # never sleeps or polls and stops on the first error. A page with
+    # has_more and no next_cursor is TransportError :malformed_response,
+    # its items unyielded.
+    def page_canvases(**filters, &block)
+      items = Enumerator.new { |out| each_item(filters, out) }
+      block ? items.each(&block) : items
+    end
+
+    private
+
+    def each_item(filters, out)
+      cursor = nil
+      loop do
+        page = list_canvases(**filters, cursor: cursor).value
+        if page.has_more && page.next_cursor.nil?
+          raise TransportError.new(:malformed_response, "a canvas page has more but no next_cursor")
+        end
+        page.items.each { |item| out << item }
+        break unless page.has_more
+        cursor = page.next_cursor
+      end
+    end
+  end
+
+  class Client
+    # The canvas operations (ADR 16.10.26ak), over this client's request
+    # path.
+    def canvases
+      @canvases ||= Canvases.new(lambda do |id, args, query, body|
+        json(id, args, query: query, body: payload(OPERATIONS.fetch(id), body))
+      end)
+    end
+  end
+end

data/lib/lingara/client.rb

@@ -282,10 +282,12 @@ module Lingara
     # the version observer, and returns what the block returns. A client with
     # no token source sends an operation that needs one without
     # Authorization; the server's 401 is the answer. +policy+ is the tail's
-    # single-attempt one for a tail open (K5a).
-    def pipeline(operation, url, body, on_start: nil, headers: {}, policy: @policy, &on_success)
+    # single-attempt one for a tail open (K5a). +allow+ is one more status
+    # yielded as a success: the export's 304 (ADR 29.10.26c D6), and nil for
+    # every other call.
+    def pipeline(operation, url, body, on_start: nil, headers: {}, policy: @policy, allow: nil, &on_success)
       send_all = lambda do |token|
-        policy.run { attempt(operation, url, body, [token, headers], on_start, &on_success) }
+        policy.run { attempt(operation, url, body, [token, headers], on_start, allow: allow, &on_success) }
       end
       result = if @token_source && operation[:needs_token]
         RetryPolicy.with_token_retry(@token_source, &send_all)
@@ -297,12 +299,13 @@ module Lingara
     end
 
     # +auth+ is the token and the call's own headers.
-    def attempt(operation, url, body, auth, on_start)
+    def attempt(operation, url, body, auth, on_start, allow: nil)
       token, extra = auth
       observe = ->(response) { @versions.observe(response, url) }
       result = @transport.request(operation[:method], url, headers(operation, body, token).merge(extra), body: body,
         read_timeout: operation[:stream] && @idle, secrets: token ? [token.expose_secret] : [], on_start: on_start) do |response, phase|
-        next Attempt.new(response: response, body: response.body.to_s) unless (200..299).cover?(response.code.to_i)
+        status = response.code.to_i
+        next Attempt.new(response: response, body: response.body.to_s) unless (200..299).cover?(status) || status == allow
         Attempt.new(value: yield(response, phase, observe), done: true)
       end
       # Phase#leave hands back the stream's value directly.

data/lib/lingara/dialogue.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Lingara
+  # What export_dialogue answers, as a Response's value (ADR 29.10.26c D6):
+  # a Body, the dialogue.v1 document as text never parsed here (its bytes
+  # are canonical and etag is their SHA-256, so store them as received), or
+  # on a 304 a NotModified: keep the copy you hold. Both carry the revision
+  # (Lingara-Dialogue-Revision) and the etag (ETag) exactly as sent.
+  module ExportedDialogue
+    Body = Data.define(:revision, :etag, :ir_json)
+    NotModified = Data.define(:revision, :etag)
+
+    # The arm a 200 or 304 answers. A missing ETag or
+    # Lingara-Dialogue-Revision, or a revision that is not a non-negative
+    # integer, is TransportError :malformed_response.
+    def self.from(response)
+      revision = response["Lingara-Dialogue-Revision"].to_s
+      etag = response["ETag"]
+      unless revision.match?(/\A\d+\z/) && etag
+        raise TransportError.new(:malformed_response, "an export needs ETag and an integer Lingara-Dialogue-Revision")
+      end
+      return NotModified.new(revision: revision.to_i, etag: etag) if response.code.to_i == 304
+      Body.new(revision: revision.to_i, etag: etag, ir_json: response.body.to_s.dup.force_encoding(Encoding::UTF_8))
+    end
+  end
+
+  # The stored-dialogue operations (ADR 29.10.26c; scopes dialogues:read and
+  # dialogues:write), reached as client.dialogues. The group holds no state
+  # of its own: every call goes through the client's request path, so the
+  # token, retries, version pin and errors are the client's. Each call
+  # returns a Response.
+  #
+  # A stale draft_version is 409 dialogue_conflict, raised as an ApiError and
+  # never retried: re-read with get_dialogue, take draft.draft_version (or
+  # send 0 when draft is nil), and decide. A replayed activate_dialogue
+  # answers 409 dialogue_conflict too, and writes nothing. Branch on an
+  # error's code, never its localised message. There is no delete: a
+  # dialogue is deleted through the platform's lifecycle routes, not this
+  # library.
+  class Dialogues
+    # Built by Client#dialogues over the client's own request path, and its
+    # export path, which reads a 304 as an answer.
+    def initialize(request, export)
+      @request = request
+      @export = export
+    end
+
+    # One page of dialogues, a DialoguePage; page_dialogues walks them.
+    def list_dialogues(cursor: nil, limit: nil, name: nil)
+      @request.call("listDialogues", [], {cursor: cursor, limit: limit, name: name}, nil)
+    end
+
+    # Creates a dialogue (201): body is {name:, definition:}. Its warnings
+    # are advice, never a refusal.
+    def create_dialogue(body)
+      @request.call("createDialogue", [], nil, body)
+    end
+
+    # One dialogue, its draft and active revision inline.
+    def get_dialogue(dialogue_id)
+      @request.call("getDialogue", [dialogue_id], nil, nil)
+    end
+
+    # Renames a dialogue (PATCH): body is {name:}.
+    def rename_dialogue(dialogue_id, body)
+      @request.call("renameDialogue", [dialogue_id], nil, body)
+    end
+
+    # Saves the draft (PUT): body is {definition:, draft_version:, name:};
+    # draft_version 0 with no draft opens one. A stale draft_version is 409
+    # dialogue_conflict, which may follow your own retried save: re-read
+    # with get_dialogue and compare first.
+    def save_dialogue_draft(dialogue_id, body)
+      @request.call("saveDialogueDraft", [dialogue_id], nil, body)
+    end
+
+    # Promotes the draft: body is {draft_version:}. A stale or missing draft
+    # is 409 dialogue_conflict and writes nothing.
+    def activate_dialogue(dialogue_id, body)
+      @request.call("activateDialogue", [dialogue_id], nil, body)
+    end
+
+    # Exports a dialogue (dialogues:read): a Response whose value is an
+    # ExportedDialogue::Body or, when +if_none_match+ (the etag you hold,
+    # sent back unchanged) still matches, an ExportedDialogue::NotModified.
+    # +revision+ is "active" or "draft", +layout+ "keep" or "omit"; each is
+    # sent only when given. A 304 still spends one unit of the rate budget.
+    # K4's retries apply.
+    def export_dialogue(dialogue_id, revision: nil, layout: nil, if_none_match: nil)
+      headers = if_none_match.nil? ? {} : {"If-None-Match" => if_none_match}
+      @export.call([dialogue_id], {revision: revision, layout: layout}, headers)
+    end
+
+    # Every DialogueSummary the filters (name:, limit:) match, following
+    # next_cursor until a page says has_more false, the filters resent on
+    # every page: an Enumerator that fetches lazily, or with a block, each
+    # item yielded. It never sleeps or polls and stops on the first error. A
+    # page with has_more and no next_cursor is TransportError
+    # :malformed_response, its items unyielded.
+    def page_dialogues(**filters, &block)
+      items = Enumerator.new { |out| each_item(filters, out) }
+      block ? items.each(&block) : items
+    end
+
+    private
+
+    def each_item(filters, out)
+      cursor = nil
+      loop do
+        page = list_dialogues(**filters, cursor: cursor).value
+        if page.has_more && page.next_cursor.nil?
+          raise TransportError.new(:malformed_response, "a dialogue page has more but no next_cursor")
+        end
+        page.items.each { |item| out << item }
+        break unless page.has_more
+        cursor = page.next_cursor
+      end
+    end
+  end
+
+  class Client
+    # The stored-dialogue operations (ADR 29.10.26c), over this client's
+    # request path.
+    def dialogues
+      @dialogues ||= Dialogues.new(
+        lambda { |id, args, query, body| json(id, args, query: query, body: payload(OPERATIONS.fetch(id), body)) },
+        lambda { |args, query, headers| export_dialogue_response(args, query, headers) }
+      )
+    end
+
+    private
+
+    # exportDialogue read by hand (D6): a 304 is an answer, the body is
+    # never decoded, and both headers are part of the result.
+    def export_dialogue_response(args, query, headers)
+      operation = OPERATIONS.fetch("exportDialogue")
+      pipeline(operation, url_for(operation, args, query), nil, headers: headers, allow: 304) do |response, _phase, observe|
+        served = observe.call(response)
+        Response.new(value: ExportedDialogue.from(response), served_version: served)
+      end
+    end
+  end
+end