mailcycle 0.1.0

data/lib/mailcycle/manage.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  # API keys, webhooks and sessions.
+  #
+  # The names on keys and webhooks are sealed here under the vault key, bound
+  # to the record's kind and id, exactly as the app seals them, so the server
+  # stores none. The id is chosen here for that reason: the name has to be
+  # bound to it before the record exists.
+  #
+  # Minting and revoking keys, and adding, changing and removing webhooks, need
+  # a signed-in session. The API answers `session_required` to an API key.
+  module Names
+    API_KEY_RECORD = "api-key"
+    WEBHOOK_RECORD = "webhook"
+
+    module_function
+
+    # A record's name, sealed as `{"name": ...}` under the vault key.
+    def seal_name(client, kind, id, name)
+      Vault.seal(client.require_keys("seal a name"), kind, id, { "name" => name })
+    end
+
+    # The name, or nil if there is no phrase or it will not open.
+    #
+    # A name that will not open is shown as unreadable rather than failing the
+    # list, the same as an address label.
+    def open_name(client, kind, id, meta)
+      Wire.maybe_text(Vault.open_or_empty(client.keys, kind, id, meta)["name"])
+    end
+  end
+
+  # API keys: list, create and revoke. Session only.
+  class ApiKeys
+    def initialize(client)
+      @client = client
+    end
+
+    # The account's keys, newest first, with their names opened.
+    def list
+      Wire.array(Wire.object(@client.http.request("GET", "/api-keys"))["apiKeys"]).map { |item| to_api_key(item) }
+    end
+
+    # Makes a key. Operator plan and up.
+    #
+    # The token comes back once, here. Keep it somewhere private; the API
+    # holds only its hash and cannot show it again.
+    def create(name)
+      id = Vault.new_id("key", 16)
+      meta = Names.seal_name(@client, Names::API_KEY_RECORD, id, name)
+      result = Wire.object(@client.http.request("POST", "/api-keys", body: { "id" => id, "meta" => meta }))
+      CreatedApiKey.new(api_key: to_api_key(result["apiKey"]), token: Wire.text(result["token"]))
+    end
+
+    # Revokes a key. It stops working at once.
+    def revoke(key_id)
+      @client.http.request("DELETE", "/api-keys/#{Mailcycle.path_segment(key_id)}")
+      nil
+    end
+
+    private
+
+    def to_api_key(wire)
+      wire = Wire.object(wire)
+      id = Wire.text(wire["id"])
+      ApiKey.new(
+        id: id,
+        name: Names.open_name(@client, Names::API_KEY_RECORD, id, wire["meta"]),
+        hint: Wire.text(wire["hint"]),
+        created_at: Wire.text(wire["createdAt"]),
+        last_used_at: Wire.maybe_text(wire["lastUsedAt"])
+      )
+    end
+  end
+
+  # Webhooks, Operator and up.
+  #
+  # A session can do everything. An API key can list, read deliveries, send a
+  # test and redeliver.
+  class Webhooks
+    def initialize(client)
+      @client = client
+    end
+
+    # The account's webhooks, with their names opened, and every event type
+    # one can subscribe to.
+    def list
+      result = Wire.object(@client.http.request("GET", "/webhook-endpoints"))
+      WebhookList.new(webhooks: Wire.array(result["webhooks"]).map { |item| to_webhook(item) },
+                      event_types: Wire.strings(result["eventTypes"]))
+    end
+
+    # Adds a webhook. `events` are event types, or `["*"]` for all of them.
+    #
+    # The signing secret comes back once, here. Keep it to check deliveries
+    # with `Mailcycle.verify_webhook_signature`.
+    def create(url, events, name)
+      id = Vault.new_id("whk", 16)
+      meta = Names.seal_name(@client, Names::WEBHOOK_RECORD, id, name)
+      body = { "id" => id, "url" => url, "events" => events, "meta" => meta }
+      result = Wire.object(@client.http.request("POST", "/webhook-endpoints", body: body))
+      CreatedWebhook.new(webhook: to_webhook(result["webhook"]), secret: Wire.text(result["secret"]))
+    end
+
+    # Changes what is given and leaves the rest. `enabled` switches it on or
+    # off.
+    def update(webhook_id, url: nil, events: nil, name: nil, enabled: nil)
+      body = {}
+      body["url"] = url unless url.nil?
+      body["events"] = events unless events.nil?
+      body["meta"] = Names.seal_name(@client, Names::WEBHOOK_RECORD, webhook_id, name) unless name.nil?
+      body["status"] = enabled ? "active" : "disabled" unless enabled.nil?
+      to_webhook(Wire.object(@client.http.request("PATCH", path(webhook_id), body: body))["webhook"])
+    end
+
+    # Removes the webhook and its delivery log.
+    def delete(webhook_id)
+      @client.http.request("DELETE", path(webhook_id))
+      nil
+    end
+
+    # A new signing secret, returned once. The old one stops at once.
+    def rotate_secret(webhook_id)
+      Wire.text(Wire.object(@client.http.request("POST", "#{path(webhook_id)}/rotate-secret", body: {}))["secret"])
+    end
+
+    # Sends a `webhook.test` event to it.
+    def test(webhook_id)
+      queued(@client.http.request("POST", "#{path(webhook_id)}/test", body: {}))
+    end
+
+    # The delivery log, newest first.
+    #
+    # `cursor` is the `next_cursor` of the page before, passed back as it is.
+    # `limit` is up to 200, 50 when it is not given.
+    def deliveries(webhook_id, cursor: nil, limit: nil)
+      query = []
+      query << ["cursor", cursor] if cursor
+      query << ["limit", limit.to_s] if limit
+      result = Wire.object(@client.http.request("GET", "#{path(webhook_id)}/deliveries", query: query))
+      DeliveryPage.new(deliveries: Wire.array(result["deliveries"]).map { |item| WebhookDelivery.from_wire(item) },
+                       next_cursor: Wire.maybe_text(result["nextCursor"]))
+    end
+
+    # Sends a delivery's event again, with the same event id.
+    def redeliver(webhook_id, delivery_id)
+      route = "#{path(webhook_id)}/deliveries/#{Mailcycle.path_segment(delivery_id)}/redeliver"
+      queued(@client.http.request("POST", route, body: {}))
+    end
+
+    private
+
+    def path(id)
+      "/webhook-endpoints/#{Mailcycle.path_segment(id)}"
+    end
+
+    def queued(result)
+      result = Wire.object(result)
+      QueuedDelivery.new(delivery_id: Wire.text(result["deliveryId"]), event_id: Wire.maybe_text(result["eventId"]))
+    end
+
+    def to_webhook(wire)
+      wire = Wire.object(wire)
+      id = Wire.text(wire["id"])
+      Webhook.new(
+        id: id,
+        name: Names.open_name(@client, Names::WEBHOOK_RECORD, id, wire["meta"]),
+        url: Wire.text(wire["url"]),
+        events: Wire.strings(wire["events"]),
+        status: Wire.text(wire["status"]),
+        disabled_reason: Wire.maybe_text(wire["disabledReason"]),
+        failing_since: Wire.maybe_text(wire["failingSince"]),
+        last_success_at: Wire.maybe_text(wire["lastSuccessAt"]),
+        created_at: Wire.text(wire["createdAt"])
+      )
+    end
+  end
+
+  # Signed-in sessions. Session only.
+  class Sessions
+    def initialize(client)
+      @client = client
+    end
+
+    # The account's live sessions, newest first. `current` marks this one.
+    def list
+      Wire.array(Wire.object(@client.http.request("GET", "/accounts/sessions"))["sessions"])
+          .map { |item| Session.from_wire(item) }
+    end
+
+    # Ends one session.
+    def revoke(session_id)
+      @client.http.request("DELETE", "/accounts/sessions/#{Mailcycle.path_segment(session_id)}")
+      nil
+    end
+
+    # Ends every session but this one. Returns how many ended.
+    def revoke_others
+      Wire.count(Wire.object(@client.http.request("DELETE", "/accounts/sessions"))["revoked"])
+    end
+  end
+end

data/lib/mailcycle/models.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  # The shapes a caller sees.
+  #
+  # Each one carries the fields the API documents. Where the API's record has
+  # room for more (a plan, a domain), anything it adds later is kept in `extra`
+  # rather than dropped, so a new server field does not need a new release to
+  # reach a caller.
+  module Wire
+    module_function
+
+    # Reading a server's JSON, which may be any shape at all: the value as the
+    # type asked for, or the fallback.
+    def object(value)
+      value.is_a?(Hash) ? value : {}
+    end
+
+    def array(value)
+      value.is_a?(Array) ? value : []
+    end
+
+    def text(value, fallback = "")
+      value.is_a?(String) ? value : fallback
+    end
+
+    def maybe_text(value)
+      value.is_a?(String) ? value : nil
+    end
+
+    def strings(value)
+      array(value).grep(String)
+    end
+
+    def count(value)
+      value.is_a?(Integer) && value >= 0 ? value : 0
+    end
+
+    def flag(value, fallback)
+      [true, false].include?(value) ? value : fallback
+    end
+  end
+
+  Plan = Struct.new(:id, :name, :extra, keyword_init: true) do
+    def self.from_wire(wire)
+      wire = Wire.object(wire)
+      new(id: Wire.text(wire["id"]), name: Wire.text(wire["name"]), extra: wire.except("id", "name"))
+    end
+  end
+
+  # `plan_id` is the account's own plan id, and `plan` is that plan's record.
+  Account = Struct.new(:id, :plan_id, :created_at, :plan, keyword_init: true)
+
+  # An email address on the account.
+  #
+  # `status` is `active` when assigned to a device, `unassigned` otherwise.
+  # `label` is the label set in the app, nil without the phrase or if it will
+  # not open. `sender_name` is the name mail from the address goes out under,
+  # nil without the phrase or if none is set. `receives` says whether the
+  # address can receive mail: it was created with its public key.
+  Address = Struct.new(:id, :email_address, :status, :created_at, :retention_days, :assigned_worker_id,
+                       :paused_at, :label, :sender_name, :receives, keyword_init: true)
+
+  # `reserved` is true for a domain that belongs to this account alone.
+  Domain = Struct.new(:domain, :reserved, :extra, keyword_init: true) do
+    def self.from_wire(wire)
+      wire = Wire.object(wire)
+      new(domain: Wire.text(wire["domain"]), reserved: Wire.flag(wire["reserved"], false),
+          extra: wire.except("domain", "reserved"))
+    end
+  end
+
+  # One file on a received message.
+  #
+  # `content_id` is set on a part the HTML shows inline, where it says `cid:`
+  # and this id. `stored` is false when the part had no body; fetching it would
+  # answer 404.
+  Attachment = Struct.new(:index, :filename, :mime_type, :size, :content_id, :stored, keyword_init: true)
+
+  # A message, opened on this machine.
+  #
+  # - `sent_via`: for sent mail, `app`, `api`, `device`, `agent` or `member`
+  #   (a team member).
+  # - `key_epoch`: the address key epoch it was sealed under. 0 unless the
+  #   address's keys were rotated.
+  # - `opened`: false when the content could not be opened: no phrase, or the
+  #   wrong one.
+  # - `reply_to`: where a reply goes: Reply-To if the sender set one,
+  #   otherwise From.
+  # - `html`: the HTML part as sent, remote images and all. Do not render this
+  #   one.
+  # - `safe_html`: the HTML with everything remote removed, as the app shows
+  #   it. `blocked` is what it had taken out of it, and who it would have told.
+  # - `message_id`: the sender's Message-ID, for threading a reply.
+  Message = Struct.new(:id, :address_id, :received_at, :read, :starred, :folder, :size_bytes, :sent_via,
+                       :key_epoch, :opened, :from_address, :from_name, :reply_to, :to, :subject, :text, :html,
+                       :safe_html, :blocked, :message_id, :attachments, keyword_init: true)
+
+  # `next_cursor` is opaque. Pass it back as it is to get the next page; nil
+  # on the last.
+  MessagePage = Struct.new(:messages, :next_cursor, keyword_init: true)
+
+  # What a send returns. `message_id` is the Message-ID the sending service
+  # gave it. `sent_copy_id` is the id of the copy kept in Sent, which the
+  # message calls take; nil when no copy was kept, as for an address without a
+  # public key.
+  SendResult = Struct.new(:message_id, :sent_copy_id, keyword_init: true)
+
+  # A paired device or agent. `name` and `tags` are what was set in the app;
+  # nil and empty without the phrase.
+  Device = Struct.new(:id, :platform, :kind, :send_mode, :status, :created_at, :last_active_at, :paused_at,
+                      :name, :tags, keyword_init: true)
+
+  # One account event from the log: ids and times, never content.
+  ActivityEntry = Struct.new(:id, :kind, :created_at, :address_id, :worker_id, keyword_init: true) do
+    def self.from_wire(wire)
+      wire = Wire.object(wire)
+      new(id: Wire.text(wire["id"]), kind: Wire.text(wire["kind"]), created_at: Wire.text(wire["createdAt"]),
+          address_id: Wire.maybe_text(wire["inboxId"]), worker_id: Wire.maybe_text(wire["workerId"]))
+    end
+  end
+
+  # One page of the event log, newest first. `next_cursor` is opaque: pass it
+  # back as it is to get the page before; nil on the last.
+  ActivityPage = Struct.new(:activity, :next_cursor, keyword_init: true)
+
+  # One event from the live stream. Events carry ids, never content.
+  AccountEvent = Struct.new(:id, :event_type, :created_at, :payload, keyword_init: true) do
+    # The event a wire value describes, or nil if it is not one.
+    def self.from_wire(wire)
+      return nil unless wire.is_a?(Hash)
+
+      id, type, created = wire.values_at("id", "type", "createdAt")
+      return nil unless [id, type, created].all? { |field| field.nil? || field.is_a?(String) }
+
+      payload = wire["payload"]
+      return nil unless payload.nil? || payload.is_a?(Hash)
+
+      new(id: id || "", event_type: type || "", created_at: created || "", payload: payload || {})
+    end
+  end
+
+  # An API key. The token itself is shown once, when it is created.
+  #
+  # `name` is the name set when it was made, opened with the phrase; nil if it
+  # will not open. `hint` is the token's last four characters. `last_used_at`
+  # is rounded down to five minutes, and nil until the key is used.
+  ApiKey = Struct.new(:id, :name, :hint, :created_at, :last_used_at, keyword_init: true)
+
+  # A new API key and its token. The token is not shown again.
+  CreatedApiKey = Struct.new(:api_key, :token, keyword_init: true)
+
+  # A webhook. `name` is opened with the phrase, nil if it will not open.
+  # `events` are event types, or `["*"]` for every event. `status` is `active`
+  # or `disabled`. `failing_since` is set while every attempt since the last
+  # success has failed.
+  Webhook = Struct.new(:id, :name, :url, :events, :status, :disabled_reason, :failing_since, :last_success_at,
+                       :created_at, keyword_init: true)
+
+  # The account's webhooks, and every event type one can ask for.
+  WebhookList = Struct.new(:webhooks, :event_types, keyword_init: true)
+
+  # A new webhook and its signing secret. The secret is not shown again.
+  CreatedWebhook = Struct.new(:webhook, :secret, keyword_init: true)
+
+  # One attempt to deliver an event to a webhook.
+  #
+  # `event` is the body as sent: type, ids and times, never content. `status`
+  # is `pending`, `succeeded` or `failed`.
+  WebhookDelivery = Struct.new(:id, :event_id, :event_type, :event, :status, :attempts, :response_status, :error,
+                               :created_at, :last_attempt_at, :next_attempt_at, keyword_init: true) do
+    def self.from_wire(wire)
+      wire = Wire.object(wire)
+      status = wire["responseStatus"]
+      new(
+        id: Wire.text(wire["id"]),
+        event_id: Wire.text(wire["eventId"]),
+        event_type: Wire.text(wire["eventType"]),
+        event: AccountEvent.from_wire(wire["event"]) || AccountEvent.new(id: "", event_type: "", created_at: "",
+                                                                         payload: {}),
+        status: Wire.text(wire["status"]),
+        attempts: Wire.count(wire["attempts"]),
+        response_status: status.is_a?(Integer) ? status : nil,
+        error: Wire.maybe_text(wire["error"]),
+        created_at: Wire.text(wire["createdAt"]),
+        last_attempt_at: Wire.maybe_text(wire["lastAttemptAt"]),
+        next_attempt_at: Wire.maybe_text(wire["nextAttemptAt"])
+      )
+    end
+  end
+
+  # `next_cursor` is opaque: pass it back as it is to get the next page; nil on
+  # the last.
+  DeliveryPage = Struct.new(:deliveries, :next_cursor, keyword_init: true)
+
+  # The delivery a test or a redelivery queued. `event_id` is set for a test,
+  # which makes a new event. A redelivery sends the original event again, id
+  # and all.
+  QueuedDelivery = Struct.new(:delivery_id, :event_id, keyword_init: true)
+
+  # A signed-in session on the account. `current` is true for the session this
+  # client is using.
+  Session = Struct.new(:id, :created_at, :expires_at, :current, keyword_init: true) do
+    def self.from_wire(wire)
+      wire = Wire.object(wire)
+      new(id: Wire.text(wire["id"]), created_at: Wire.text(wire["createdAt"]),
+          expires_at: Wire.text(wire["expiresAt"]), current: Wire.flag(wire["current"], false))
+    end
+  end
+
+  # The account's subscription, balance, and any pause after a missed payment.
+  #
+  # `pending_plan_id` is the plan the account moves to when the paid month runs
+  # out. `balance_minor` is the account balance, in minor units. `pause` is
+  # what a missed payment has paused, and when it is deleted; nil when nothing
+  # is paused.
+  Subscription = Struct.new(:id, :plan_id, :status, :renewal_date, :pending_plan_id, :balance_minor, :pause,
+                            keyword_init: true)
+
+  # The kind of name the server rolls for a new address.
+  module NameStyle
+    # Like `maya.holt`.
+    PERSON = "person"
+    # Like `harbor-supply42`.
+    BUSINESS = "business"
+    # Like `support_desk`.
+    TEAM = "team"
+    # Like `quiet_falcon`. What the server rolls when no style is given.
+    NEUTRAL = "neutral"
+    ALL = [PERSON, BUSINESS, TEAM, NEUTRAL].freeze
+
+    # The name the API uses, from a symbol or a string.
+    def self.wire(style)
+      name = style.to_s
+      unless ALL.include?(name)
+        raise ArgumentError,
+              "Unknown name style #{style.inspect}: use one of #{ALL.join(', ')}."
+      end
+
+      name
+    end
+  end
+end