calmlens 0.1.0

data/lib/calmlens/testing.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'uri'
+require_relative '../calmlens'
+require_relative 'testing/fake_api'
+
+module CalmLens
+  # An offline client for tests. Calls run the real client's validation, encoding, retries and
+  # error handling, then reach an in-memory stand-in for the API and CDN instead of the network.
+  #
+  # By default the stand-in is stateful: uploads create assets you can retrieve, list, filter,
+  # move and delete, folders behave like the API's, the CDN serves stored bytes, and errors use
+  # the API's codes, HTTP statuses and body shape. It does not classify content: assets moderated
+  # synchronously get `analyzed_outcome` and queued ones `queued_outcome`. Content is kept only with
+  # `keepContentAfterProcessing: true`; otherwise it is removed once processing is `done`, as in the API.
+  #
+  # To script exact responses, enqueue them: queued responses and errors are used first, in order,
+  # before the stand-in answers.
+  #
+  # @example
+  #   mock = CalmLens::MockServerClient.new
+  #   asset = mock.assets.moderate(name: 'note', content: {plain_text: 'hi', type: 'text/plain'})
+  #   mock.assets.retrieve(asset_id: asset['id']).dig('moderation', 'status') # => "approved"
+  #   mock.enqueue(status: 503, body: {code: 'server/unavailable', message: 'Try again'})
+  class MockServerClient < ServerClient
+    # A request the mock received.
+    #
+    # `path` is relative to `base_url` for API calls (`/projects/<id>/assets`) and to
+    # `cdn_base_url` for CDN requests. `query` holds the decoded query string. `body` is the bytes
+    # sent: JSON text, or the uploaded content (streams are read), or nil.
+    Request = Struct.new(:method, :url, :path, :query, :headers, :body, keyword_init: true) do
+      # @return [Object] the body parsed as JSON.
+      def json = body && JSON.parse(body)
+    end
+
+    # @return [Testing::State] the stored assets, folders, content and events.
+    attr_reader :state
+
+    # @param project_id [String]
+    # @param now [#call] returns the current time in epoch milliseconds.
+    # @param create_id [#call] returns a new ID.
+    # @param queued_outcome [String] the outcome of assets created with {Assets#create}: `pending`
+    #   (processing, moderation pending), `approved` or `rejected` (processing done with that
+    #   decision) or `failed` (processing failed, retryable).
+    # @param analyzed_outcome [String, Hash, #call] the result of {Assets#moderate}: an outcome, fields
+    #   to deep-merge into the asset (`{'moderation' => {'status' => 'rejected', 'action' => 'hide'}}`;
+    #   the outcome follows `moderation.status`, or is `failed` when `processing.status` is `failed`,
+    #   and is `approved` otherwise), or a callable that receives a copy of the asset and returns either.
+    # @param options [Hash] other {ServerClient#initialize} settings, except `api_key` and `transport`.
+    #   Retries wait no time unless a queued response sets `Retry-After`.
+    def initialize(project_id: 'project-1', base_url: 'https://api.calmlens.invalid/v1',
+                   cdn_base_url: 'https://cdn.calmlens.invalid/v1', now: -> { (Time.now.to_f * 1000).to_i },
+                   create_id: -> { SecureRandom.uuid }, queued_outcome: 'pending', analyzed_outcome: 'approved',
+                   **options)
+      @mock_lock = Mutex.new
+      @queue = []
+      @received = []
+      super(api_key: 'mock-key', project_id: project_id, base_url: base_url, cdn_base_url: cdn_base_url,
+            retry_base_delay: 0, **options, transport: method(:receive))
+      @fake = Testing::FakeAPI.new(project_id: project_id, base_url: self.base_url, cdn_base_url: self.cdn_base_url,
+                                   now: now, create_id: create_id, queued_outcome: queued_outcome,
+                                   analyzed_outcome: analyzed_outcome)
+      @state = @fake.state
+    end
+
+    # Queues a JSON response for the next request.
+    # @param status [Integer]
+    # @param body [Object] encoded as JSON
+    # @param headers [Hash{String => String}]
+    # @return [self]
+    def enqueue(body:, status: 200, headers: {})
+      enqueue_raw(status: status, body: JSON.generate(body), headers: { 'content-type' => 'application/json' }.merge(headers))
+    end
+
+    # Queues a response with a raw body, such as malformed JSON or binary CDN content.
+    # @return [self]
+    def enqueue_raw(body:, status: 200, headers: {})
+      response = Response.new(status: status, body: body.to_s.dup,
+                              headers: { 'x-request-id' => "mock-#{SecureRandom.hex(8)}" }.merge(headers))
+      @mock_lock.synchronize { @queue << response }
+      self
+    end
+
+    # Fails the next request with an exception raised by the transport, such as
+    # `Net::ReadTimeout.new` (raised as `sdk/timeout`) or `Errno::ECONNRESET.new`
+    # (`sdk/transport-error`). The client wraps it exactly as it wraps real network failures.
+    # @return [self]
+    def enqueue_error(error)
+      @mock_lock.synchronize { @queue << error }
+      self
+    end
+
+    # Adds an event to the mock's events feed. Fields you omit (`id`, `projectId`, `createdAt`,
+    # `severity`, `title`, `facts`) are filled in.
+    # @param event [Hash] at least `type:`; snake_case keys are converted.
+    # @return [Hash] the stored event
+    def enqueue_event(event)
+      @mock_lock.synchronize { JSON.parse(JSON.generate(@fake.add_event(Internal.normalize(event)))) }
+    end
+
+    # @return [Array<Request>] copies of every request received so far, oldest first.
+    def requests
+      @mock_lock.synchronize { @received.map { |request| Request.new(**Marshal.load(Marshal.dump(request.to_h))) } }
+    end
+
+    # @return [Integer] queued responses and errors not used yet.
+    def remaining_responses
+      @mock_lock.synchronize { @queue.size }
+    end
+
+    def inspect = "#<#{self.class.name} project_id=#{project_id.inspect}>"
+
+    private
+
+    # Returns the response rather than yielding it: the client accepts either from a transport.
+    def receive(request, &)
+      body = request.body.respond_to?(:read) ? read_stream(request.body) : request.body&.b
+      path, query = Internal.split_url(request.url).last.split('?', 2)
+      base = request.url.start_with?("#{cdn_base_url}/") ? URI(cdn_base_url).path : URI(base_url).path
+      @mock_lock.synchronize do
+        @received << Request.new(method: request.method, url: request.url, path: path.delete_prefix(base),
+                                 query: URI.decode_www_form(query.to_s).to_h, headers: request.headers.dup,
+                                 body: body)
+        queued = @queue.shift
+        raise queued if queued.is_a?(Exception)
+
+        queued || @fake.handle(request.method, request.url, request.headers, body)
+      end
+    end
+
+    def read_stream(io)
+      buffer = String.new(encoding: Encoding::BINARY)
+      while (chunk = io.read(64 * 1024))
+        buffer << chunk
+      end
+      buffer
+    end
+  end
+end

data/lib/calmlens/text.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # Text moderation shortcuts. Reach it through {ServerClient#text}.
+  class Text < Resource
+    # @api private
+    def initialize(session, assets)
+      super(session)
+      @assets = assets
+    end
+
+    # Moderates a string as a `text/plain` asset and waits for the decision.
+    # @option options [String] :text
+    # @option options [String] :name defaults to `text`
+    # @return [Hash] the asset; publish only when `moderation.status` is `approved` and
+    #   `moderation.action` is nil.
+    def moderate(options)
+      api, request = call(options) { |*split| split }
+      text = api['text']
+      unless text.is_a?(String) && !text.strip.empty?
+        raise Internal.invalid('Text to moderate must be a non-empty string', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      end
+
+      @assets.moderate(without(api, 'text').merge('name' => api.fetch('name', 'text'),
+                                                  'content' => { 'plainText' => text, 'type' => 'text/plain' },
+                                                  'request_options' => request))
+    end
+  end
+end

data/lib/calmlens/transforms.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # CDN transform selectors: selector Strings and structured steps serialized the way every SDK does.
+  # @api private
+  module Transforms
+    module_function
+
+    TYPE = /\A[A-Za-z0-9_]+\z/
+
+    # Returns the selector the API and CDN accept for a transform: a selector String unchanged, or
+    # structured steps (`{type:, options:}` or an Array of them) serialized by {serialize}.
+    def selector(value)
+      value.nil? || value.is_a?(String) ? value : serialize(value)
+    end
+
+    # Builds the CDN path of a transform. A selector String keeps its own separators and literal
+    # `[`/`]`, which the CDN matches; serialized steps are already path-safe.
+    def path(value)
+      return serialize(value) unless value.is_a?(String)
+
+      text = value.sub(%r{\A/+}, '')
+      raise Internal.invalid('Transform cannot contain "..", "?" or "#"') if text.include?('..') || text.match?(/[?#]/)
+
+      # Like JavaScript's encodeURI, except that brackets stay literal.
+      text.b.gsub(%r{[^A-Za-z0-9\-_.!~*'();/:@&=+$,\[\]]}n) { |byte| format('%%%02X', byte.ord) }
+    end
+
+    # Serializes structured transforms as a CDN selector such as `imageTransform[format=png,width=1024]`.
+    # Option keys are sorted so equal transforms share a URL; nested keys (`border[color]`) and values
+    # are percent-encoded.
+    def serialize(value)
+      steps = value.is_a?(Array) ? value : [value]
+      raise Internal.invalid('Transform needs at least one step') if steps.empty?
+
+      steps.map do |step|
+        raise Internal.invalid('Transform steps must be Hashes') unless step.is_a?(Hash)
+
+        step = step.transform_keys(&:to_s)
+        type = step['type']
+        unless type.is_a?(String) && type.match?(TYPE)
+          raise Internal.invalid('Transform type must contain only letters, digits and underscores')
+        end
+
+        options = step['options'] || {}
+        raise Internal.invalid('Transform options must be a Hash') unless options.is_a?(Hash)
+
+        pairs = []
+        sorted_options(options).each { |key, item| append_pairs(pairs, key, item) }
+        "#{type}[#{pairs.join(',')}]"
+      end.join(',')
+    end
+
+    def sorted_options(options) = options.map { |key, item| [key.to_s, item] }.sort_by(&:first)
+
+    def append_pairs(pairs, key, value)
+      return if value.nil?
+      return sorted_options(value).each { |child, item| append_pairs(pairs, "#{key}[#{child}]", item) } if value.is_a?(Hash)
+
+      text = case value
+             when String, true, false, Integer then value.to_s
+             when Float
+               raise Internal.invalid("Transform option \"#{key}\" must be a finite number") unless value.finite?
+
+               js_number(value)
+             else raise Internal.invalid("Transform option \"#{key}\" must be a String, number, boolean or Hash")
+             end
+      pairs << "#{component(key)}=#{component(text)}"
+    end
+
+    # Percent-encodes everything except RFC 3986 unreserved characters.
+    def component(text)
+      text.encode(Encoding::UTF_8).b.gsub(/[^A-Za-z0-9\-._~]/n) { |byte| format('%%%02X', byte.ord) }
+    end
+
+    # Formats a Float the way JavaScript's String(number) does, so every SDK builds the same URL.
+    def js_number(value)
+      return '0' if value.zero?
+
+      mantissa, exponent = value.abs.to_s.split('e')
+      whole, fraction = mantissa.split('.')
+      digits = "#{whole}#{fraction}"
+      point = whole.length + exponent.to_i
+      stripped = digits.sub(/\A0+/, '')
+      point -= digits.length - stripped.length
+      digits = stripped.sub(/0+\z/, '')
+      sign = value.negative? ? '-' : ''
+      "#{sign}#{js_digits(digits, point)}"
+    end
+
+    # Places a decimal point in significant `digits` whose value is 0.digits x 10^point.
+    def js_digits(digits, point)
+      size = digits.length
+      if point.between?(size, 21) then digits + ('0' * (point - size))
+      elsif point.positive? && point <= 21 then "#{digits[0, point]}.#{digits[point..]}"
+      elsif point > -6 && point <= 0 then "0.#{'0' * -point}#{digits}"
+      else
+        shown = size > 1 ? "#{digits[0]}.#{digits[1..]}" : digits
+        "#{shown}e#{point - 1 >= 0 ? '+' : '-'}#{(point - 1).abs}"
+      end
+    end
+  end
+  private_constant :Transforms
+end

data/lib/calmlens/transport.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'openssl'
+require 'uri'
+require 'zlib'
+
+module CalmLens
+  # The HTTP layer. Pass a custom transport to {ServerClient#initialize} to route requests elsewhere;
+  # it receives a {Transport::Request} and either returns a {Response} or yields one to the block
+  # it is given (and returns the block's result), which lets the body stream.
+  module Transport
+    # One outgoing HTTP request.
+    #
+    # @!attribute method [String] the HTTP method.
+    # @!attribute url [String] the absolute URL.
+    # @!attribute headers [Hash{String => String}]
+    # @!attribute body [String, #read, nil] the request body. A streamed body has a `Content-Length` header.
+    # @!attribute open_timeout [Numeric] seconds allowed to open a connection.
+    # @!attribute timeout [Numeric] seconds allowed for each read or write; not a whole-transfer deadline.
+    Request = Struct.new(:method, :url, :headers, :body, :open_timeout, :timeout, keyword_init: true) do
+      def inspect = "#<#{self.class.name} #{method} #{url}>"
+    end
+
+    # Exceptions that mean the connection failed before a complete response arrived.
+    ERRORS = [IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::ProtocolError,
+              Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Zlib::Error].freeze
+
+    # The default transport: Net::HTTP with a small per-origin pool of keep-alive connections.
+    # Redirects are never followed, so credentials never reach another host. After `fork`, the
+    # child process discards the inherited connections and opens its own.
+    class NetHTTP
+      MAX_IDLE_PER_ORIGIN = 8
+
+      def initialize
+        @lock = Mutex.new
+        @idle = {}
+        @closed = false
+        @pid = Process.pid
+      end
+
+      # @param request [Request]
+      # @yieldparam response [Response] a response whose body streams from the socket.
+      def call(request)
+        uri, target = Internal.split_url(request.url)
+        origin = [uri.scheme, uri.host, uri.port]
+        connection = checkout(origin)
+        reusable = false
+        begin
+          connection ||= connect(uri, request.open_timeout)
+          connection.read_timeout = connection.write_timeout = request.timeout
+          result = nil
+          connection.request(build(target, request)) do |net|
+            response = Response.new(status: net.code, headers: net.to_hash) { |&chunk| net.read_body(&chunk) }
+            result = yield response
+            reusable = !net['connection'].to_s.casecmp?('close')
+          end
+          result
+        ensure
+          checkin(origin, connection, reusable) if connection
+        end
+      end
+
+      # Closes idle connections. Later requests fail.
+      def close
+        @lock.synchronize do
+          @closed = true
+          @idle.each_value { |connections| connections.each { |connection| finish(connection) } }
+          @idle.clear
+        end
+      end
+
+      def inspect = "#<#{self.class.name}>"
+
+      private
+
+      def build(target, request)
+        net = Net::HTTPGenericRequest.new(request.method, !request.body.nil?, request.method != 'HEAD',
+                                          target, request.headers)
+        if request.body.respond_to?(:read)
+          net.body_stream = request.body
+        elsif request.body
+          net.body = request.body
+        end
+        net
+      end
+
+      def connect(uri, open_timeout)
+        connection = Net::HTTP.new(uri.host, uri.port)
+        connection.use_ssl = uri.scheme == 'https'
+        connection.open_timeout = open_timeout
+        # Retries are decided by the client, which knows which requests are safe to repeat.
+        connection.max_retries = 0
+        connection.start
+        connection
+      end
+
+      def checkout(origin)
+        @lock.synchronize do
+          raise ConnectionError.new(SdkErrorCodes::TRANSPORT_ERROR, 'Client is closed') if @closed
+
+          # Sockets inherited across fork are shared with the parent: drop them without closing.
+          if @pid != Process.pid
+            @idle = {}
+            @pid = Process.pid
+          end
+          (@idle[origin] ||= []).pop
+        end
+      end
+
+      def checkin(origin, connection, reusable)
+        kept = @lock.synchronize do
+          idle = (@idle[origin] ||= [])
+          if reusable && !@closed && @pid == Process.pid && idle.size < MAX_IDLE_PER_ORIGIN
+            idle << connection
+            true
+          end
+        end
+        finish(connection) unless kept
+      end
+
+      def finish(connection)
+        connection.finish if connection.started?
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/calmlens/upload_body.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # An upload payload: a binary String, or an IO streamed with an exact byte count.
+  # @api private
+  class UploadBody
+    PAYLOAD_KEYS = %w[plainText base64 data bytes].freeze
+    MIN_PART_BYTES = 5 * 1024 * 1024
+
+    attr_reader :size
+
+    # Builds the body from upload content options (`plainText`, `base64`, or `data`/`bytes` as a
+    # String or IO). IO input is streamed, never read into memory.
+    def self.from(content, multipart:)
+      raise Internal.invalid('Upload content must be a Hash', ErrorCodes::INVALID_UPLOAD_PAYLOAD) unless content.is_a?(Hash)
+
+      keys = PAYLOAD_KEYS.select { |key| content.key?(key) }
+      raise Internal.invalid('Supply exactly one payload representation', ErrorCodes::INVALID_UPLOAD_PAYLOAD) unless keys.size == 1
+
+      body = build(keys.first, content.fetch(keys.first), content['sizeInBytes'], multipart)
+      if content.key?('sizeInBytes') && content['sizeInBytes'] != body.size
+        raise Internal.invalid('sizeInBytes must match the payload byte length', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      end
+      if multipart && !content.fetch('isFinal', false) && body.size < MIN_PART_BYTES
+        raise Internal.invalid('Multipart upload parts must be at least 5MiB except the final part.',
+                               ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      end
+      body
+    end
+
+    def self.build(kind, value, declared, multipart)
+      case kind
+      when 'plainText'
+        raise Internal.invalid('plainText must be a String', ErrorCodes::INVALID_UPLOAD_PAYLOAD) unless value.is_a?(String)
+
+        new(value.encode(Encoding::UTF_8).b)
+      when 'base64' then new(decode64(value, multipart))
+      else
+        return new(value.b) if value.is_a?(String)
+        return new(IOReader.new(value, stream_size(value, declared))) if value.respond_to?(:read)
+
+        raise Internal.invalid('Expected a binary String or IO', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      end
+    end
+
+    def self.decode64(value, multipart)
+      raise Internal.invalid('base64 must be a String', ErrorCodes::INVALID_UPLOAD_PAYLOAD) unless value.is_a?(String)
+
+      raw = value.split(';base64,').last.to_s.gsub(/\s/, '')
+      if multipart && raw.length % 4 != 0
+        raise Internal.invalid('Split bytes before base64-encoding each part', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+      end
+
+      (raw + ('=' * ((4 - (raw.length % 4)) % 4))).unpack1('m0')
+    rescue ArgumentError
+      raise Internal.invalid('Invalid base64', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+    end
+
+    # The bytes left in a sized stream (a File, Tempfile or StringIO), or the declared size.
+    def self.stream_size(io, declared)
+      return declared if declared.is_a?(Integer) && declared >= 0
+
+      remaining = io.size - io.pos if io.respond_to?(:size) && io.respond_to?(:pos)
+      return remaining if remaining.is_a?(Integer) && remaining >= 0
+
+      raise Internal.invalid('Pass sizeInBytes for a stream whose length is unknown', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+    rescue IOError, SystemCallError, NoMethodError
+      raise Internal.invalid('Pass sizeInBytes for a stream whose length is unknown', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+    end
+    private_class_method :build, :decode64, :stream_size
+
+    def initialize(source)
+      @source = source
+      @size = source.is_a?(String) ? source.bytesize : source.size
+    end
+
+    # @return [String, IOReader] what the transport sends.
+    def content
+      @source
+    end
+
+    # @return [Boolean] whether the body can be sent again for a retry.
+    def replayable?
+      @source.is_a?(String) || @source.rewindable?
+    end
+
+    # Prepares the body to be sent again.
+    def rewind
+      @source.rewind unless @source.is_a?(String)
+    end
+
+    # The bytes, read fully. Used only by the offline mock.
+    def read_all
+      return @source if @source.is_a?(String)
+
+      @source.rewind if @source.rewindable?
+      @source.read || ''.b
+    end
+
+    # Reads exactly `size` bytes from an IO and fails if it holds fewer or more.
+    class IOReader
+      attr_reader :size
+
+      def initialize(io, size)
+        @io = io
+        @size = size
+        @remaining = size
+        @start = (io.pos if io.respond_to?(:pos) && io.respond_to?(:seek))
+      rescue IOError, SystemCallError
+        @start = nil
+      end
+
+      def rewindable? = !@start.nil?
+
+      def rewind
+        @io.seek(@start)
+        @remaining = @size
+      end
+
+      def read(length = nil, buffer = nil)
+        return (buffer ? buffer.replace(''.b) : ''.b) if length&.zero?
+
+        if @remaining.zero?
+          extra = @io.read(1)
+          unless extra.nil? || extra.empty?
+            raise Internal.invalid('The stream holds more bytes than sizeInBytes',
+                                   ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+          end
+
+          buffer&.clear
+          return length.nil? || length.zero? ? ''.b : nil
+        end
+        chunk = @io.read([length || @remaining, @remaining].min)
+        if chunk.nil? || chunk.empty?
+          raise Internal.invalid('The stream ended before sizeInBytes bytes', ErrorCodes::INVALID_UPLOAD_PAYLOAD)
+        end
+
+        @remaining -= chunk.bytesize
+        chunk = chunk.b
+        buffer ? buffer.replace(chunk) : chunk
+      end
+
+      def readpartial(length, buffer = nil)
+        read(length, buffer) || raise(EOFError)
+      end
+    end
+  end
+  private_constant :UploadBody
+end

data/lib/calmlens/upload_tokens.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'openssl'
+require 'securerandom'
+
+module CalmLens
+  # Signs upload tokens, which let a browser upload through an upload preset. Reach it through
+  # {ServerClient#upload_tokens}. Signing happens locally with the API key; no request is made.
+  class UploadTokens < Resource
+    TOKEN_PREFIX = 'clut_'
+    SIGNING_CONTEXT = 'calmlens-upload-token:v1:'
+    DEFAULT_TTL_SECONDS = 600
+    MAX_TTL_SECONDS = 3600
+
+    # @api private
+    def initialize(session, api_key)
+      super(session)
+      @api_key = api_key
+    end
+
+    # Signs a single-use token. Hand it to the browser as its bearer token; give each upload its own.
+    # @option options [String] :upload_preset_id the preset the token may upload through
+    # @option options [String] :external_id the external ID the uploaded asset gets (not empty)
+    # @option options [Integer] :expires_in_seconds lifetime, 1 to 3600 (default 600)
+    # @return [Hash] `{'token' => String, 'expiresAt' => Integer}` (milliseconds since the Unix epoch)
+    def sign(options)
+      api, = call(options) { |*split| split }
+      preset_id = api['uploadPresetId']
+      Internal.segment(preset_id)
+      ttl = api.fetch('expiresInSeconds', DEFAULT_TTL_SECONDS)
+      unless ttl.is_a?(Integer) && ttl.between?(1, MAX_TTL_SECONDS)
+        raise Internal.invalid("expiresInSeconds must be a whole number from 1 to #{MAX_TTL_SECONDS}")
+      end
+
+      external_id = api['externalId']
+      if api.key?('externalId') && !(external_id.is_a?(String) && !external_id.empty?)
+        raise Internal.invalid('externalId must be a non-empty string')
+      end
+
+      expires_at = (Time.now.to_f * 1000).to_i + (ttl * 1000)
+      claims = { 'v' => 1, 'u' => preset_id, 'k' => @api_key[0, @api_key.start_with?('clsk_') ? 13 : 8],
+                 'e' => expires_at, 'n' => SecureRandom.uuid }
+      claims['x'] = external_id if external_id
+      body = [JSON.generate(claims)].pack('m0').tr('+/', '-_').delete('=')
+      secret = Digest::SHA256.hexdigest(@api_key)
+      signature = OpenSSL::HMAC.hexdigest('SHA256', secret, SIGNING_CONTEXT + body)
+      { 'token' => "#{TOKEN_PREFIX}#{body}.#{signature}", 'expiresAt' => expires_at }
+    end
+  end
+end

data/lib/calmlens/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # The gem version. The gemspec and the User-Agent header read it from here.
+  VERSION = '0.1.0'
+end