crest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cad1f39fb20344579f8ba34190bf9ee7dc17f8fa4bea75a581f9219c74cc589
+  data.tar.gz: a227eaf7e1d5fc43864fcb9ce019e3e9575703549e72cdad8a5a22667716c6fc
+SHA512:
+  metadata.gz: e18330c407056f688bc665a6f01588204a9faf5036fd2088802d73891cc506fdb8e31c50a0c456f6fa85da653b3af22d2c15e0b0d314b3e2dd91da2522e9af55
+  data.tar.gz: 5f4db2d8af24f882704f0b83af41122739fe294f56859cb9f1df435b1090409ab27760e954022c8496178a3ddbe65b04189a0088216acc94ec99b0ed5ce8b7b2

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
+[Vandamme](http://tech-angels.github.io/vandamme).
+
+## [Unreleased]
+
+## 0.1.0 - 2026-09-11
+
+* [Feature] Build a vCard 3.0 from a name, a number and whatever else is worth saving --
+  `Crest::Card.new(name:, phone:, url:, email:, org:, photo:).to_s` -- CRLF-delimited, folded at
+  74 characters with the continuation space the format asks for, and with the photo typed PNG or
+  JPEG by its own first bytes rather than by anything the caller declares. Plain Ruby: it loads
+  and answers with no Rails in the process
+* [Feature] Draw the card at a path the host names with `crest 'houseaccount.vcf'`, a routes DSL
+  method rather than an engine to mount, so the line may sit inside a `scope` or a `constraints`.
+  The controller it draws to descends from `ActionController::Base` and not from the host's
+  `ApplicationController`, since the card is public by definition and an inherited
+  `before_action :authenticate` would refuse the one request it exists to answer
+* [Feature] State the name, number, URL, email, organization and picture in one initializer, each
+  of them a value or a callable resolved per request, so a number read out of the environment is
+  right in production and in staging without a restart

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Claudio Baccigalupo
+
+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,91 @@
+# Crest
+
+A contact card your Rails app hands out, so a text from an unknown number arrives under a name.
+
+`GET /houseaccount.vcf` answers with a vCard. A phone offers to save it, and from then on your
+messages come from *HouseAccount* rather than from `+1 800 555 0100`.
+
+## How to install
+
+```sh
+gem install crest
+```
+
+Or, in your `Gemfile`:
+
+```ruby
+gem 'crest', '~> 0.1.0'
+```
+
+Crest is below `1.0`, so the pin stops short of `0.2.0` rather than admitting every `0.x`:
+`~> major.minor` only promises what it says once the major is real. From `1.0` on it will be
+`~> 1.0`, and `bundle update` will never cross a breaking change.
+
+## Handing out a card
+
+One line in `config/routes.rb`:
+
+```ruby
+crest 'houseaccount.vcf'
+```
+
+and one initializer, `config/initializers/crest.rb`:
+
+```ruby
+Crest.configure do |config|
+  config.name  = 'HouseAccount'
+  config.org   = 'HouseAccount'
+  config.url   = 'https://houseaccount.com/'
+  config.email = 'hello@houseaccount.com'
+  config.photo = Rails.root.join 'public/cube.png'
+  config.phone = -> { Delivery::Twilio.sender }
+end
+```
+
+That is the whole of it. The route gives you a `houseaccount_vcf_path` helper to link to, and
+the response is `text/vcard`, named after the file, and cacheable.
+
+Only `name` and `phone` are required, and the gem raises rather than handing out a card that
+saves under a blank name. Everything else is left out of the card when you do not set it.
+
+**Every setting may be a value or a callable**, and a callable is asked again on every request.
+That is what makes a number read out of the environment safe: production and staging differ, and
+a value read once at boot would be wrong in one of them until a restart.
+
+The picture is bytes, or a path the gem reads. It is read from disk once, and PNG and JPEG are
+told apart by the image's own first bytes rather than by anything you have to declare.
+
+## Why a route and not an engine to mount
+
+You name the path, because the filename is your app's own name. And because it is a route rather
+than an engine, the line goes wherever you want it — inside a `scope`, behind a `constraints`,
+under a subdomain — which a mount point cannot do.
+
+## Why the controller is not your ApplicationController
+
+`Crest::CardsController` descends from `ActionController::Base`, not from your
+`ApplicationController`. That is deliberate and it is the surprising half: the card is public by
+definition — a phone fetches it with no session — so an inherited `before_action :authenticate`
+would refuse the one request the gem exists to answer.
+
+## Without Rails
+
+The builder is plain Ruby and loads on its own, Rails or no Rails:
+
+```ruby
+require 'crest/card'
+
+Crest::Card.new(name: 'HouseAccount', phone: '+18005550100',
+                url: 'https://houseaccount.com/', photo: 'cube.png').to_s
+```
+
+It answers a vCard 3.0 string, CRLF-delimited and folded at 74 characters with the continuation
+space the format asks for.
+
+## Documentation
+
+The API reference is at [rubydoc.info/gems/crest](https://rubydoc.info/gems/crest).
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/lib/crest/card.rb

@@ -0,0 +1,49 @@
+require 'crest/photo'
+
+module Crest
+  # A contact card a phone offers to save, written as the vCard 3.0 every phone reads.
+  class Card
+    # What a line may hold before a vCard folds it, less the space that continues it.
+    FOLD = 74
+
+    # @param name [String] name the card is saved under.
+    # @param phone [String] number in the form a phone should dial it.
+    # @param url [String] address of the site behind the name.
+    # @param email [String] address somebody may write back to.
+    # @param org [String] organization the name stands for.
+    # @param photo [String, Pathname] image bytes, or the file to read them from.
+    def initialize(name:, phone:, url: nil, email: nil, org: nil, photo: nil)
+      @name = name
+      @phone = phone
+      @url = url
+      @email = email
+      @org = org
+      @photo = photo
+    end
+
+    # @return [String] card itself, CRLF-delimited and folded, as the format asks.
+    def to_s = lines.flat_map { |line| fold line }.join("\r\n") << "\r\n"
+
+  private
+
+    def lines
+      [
+        'BEGIN:VCARD', 'VERSION:3.0',
+        "N:;#{@name};;;", "FN:#{@name}",
+        ("ORG:#{@org}" if @org),
+        "TEL;TYPE=CELL:#{@phone}",
+        ("URL:#{@url}" if @url),
+        ("EMAIL;TYPE=INTERNET:#{@email}" if @email),
+        (Photo.of(@photo).to_s if @photo),
+        'END:VCARD',
+      ].compact
+    end
+
+    def fold(line)
+      return [line] if line.length <= FOLD
+
+      # A long line continues on the next one, which a single space marks as the same line.
+      [line[0, FOLD], *line[FOLD..].scan(/.{1,#{FOLD - 1}}/).map { |part| " #{part}" }]
+    end
+  end
+end

data/lib/crest/cards_controller.rb

@@ -0,0 +1,19 @@
+module Crest
+  # Hands out the contact card. It descends from ActionController::Base rather than from the
+  # host's ApplicationController on purpose: the card is public by definition, and an inherited
+  # `before_action :authenticate` would refuse the one request this exists to answer.
+  class CardsController < ActionController::Base
+    # What a phone has to be told the body is before it offers to save it.
+    TYPE = 'text/vcard; charset=utf-8'
+
+    # Answers the card, named after the path it was drawn at and cached until the card changes.
+    # @return [void]
+    def show
+      card = Crest.card.to_s
+
+      if stale?(etag: card, public: true)
+        send_data card, type: TYPE, disposition: 'inline', filename: File.basename(request.path)
+      end
+    end
+  end
+end

data/lib/crest/config.rb

@@ -0,0 +1,36 @@
+require 'crest/error'
+
+module Crest
+  # Every fact about the app a card is handed out by, so none of the gem's own classes names one.
+  # A host states each as a value or as something callable, and a callable is asked every time a
+  # card is drawn: an app reading its number out of the environment differs between production and
+  # staging, and one read at boot would be wrong in one of them until a restart.
+  class Config
+    # What a host states, each resolved when a card is drawn rather than when this is written.
+    attr_writer :name, :phone, :url, :email, :org, :photo
+
+    # @return [String] name the card is saved under, which the gem cannot invent.
+    def name = resolve(@name) || missing('name')
+
+    # @return [String] number a text of ours arrives from, which the gem cannot invent.
+    def phone = resolve(@phone) || missing('phone')
+
+    # @return [String] address of the site behind the name, left out of the card where unset.
+    def url = resolve @url
+
+    # @return [String] address somebody may write back to, left out of the card where unset.
+    def email = resolve @email
+
+    # @return [String] organization the name stands for, left out of the card where unset.
+    def org = resolve @org
+
+    # @return [String, Pathname] picture the card carries, left out of the card where unset.
+    def photo = resolve @photo
+
+  private
+
+    def resolve(setting) = setting.respond_to?(:call) ? setting.call : setting
+
+    def missing(setting) = raise(Error, "Crest.config.#{setting} has to be set")
+  end
+end

data/lib/crest/error.rb

@@ -0,0 +1,4 @@
+module Crest
+  # Raised for every failure the gem reports, so hosts can rescue one type.
+  class Error < StandardError; end
+end

data/lib/crest/photo.rb

@@ -0,0 +1,32 @@
+require 'crest/error'
+
+module Crest
+  # The picture a card carries: bytes as they were handed over, or the file a path names.
+  class Photo
+    # The first bytes of each image format a phone will read a saved card's picture from.
+    SIGNATURES = { 'PNG' => "\x89PNG".b, 'JPEG' => "\xFF\xD8\xFF".b }
+
+    # The picture a path or a string of bytes stands for, read from disk only the first time,
+    # so a card handed out a thousand times costs one read and one encoding.
+    # @return [Crest::Photo] picture that file holds, or those bytes are.
+    def self.of(photo)
+      @read ||= {}
+      @read[photo] ||= new photo
+    end
+
+    # @param photo [String, Pathname] image bytes, or the file to read them from.
+    def initialize(photo)
+      @bytes = photo.respond_to?(:binread) ? photo.binread : photo
+    end
+
+    # @return [String] PHOTO property, base64-encoded and typed by the image's own first bytes.
+    def to_s = @property ||= "PHOTO;ENCODING=b;TYPE=#{type}:#{[@bytes].pack 'm0'}"
+
+  private
+
+    def type
+      SIGNATURES.find { |_, signature| @bytes.b.start_with? signature }&.first ||
+        raise(Error, 'a photo has to be a PNG or a JPEG')
+    end
+  end
+end

data/lib/crest/railtie.rb

@@ -0,0 +1,14 @@
+require 'crest/routes'
+
+module Crest
+  # Teaches a host's routes file the `crest` method, and loads the controller that answers it.
+  class Railtie < ::Rails::Railtie
+    initializer 'crest.routes' do |app|
+      ActionDispatch::Routing::Mapper.include Crest::Routes
+
+      # Loaded once the routes are drawn, so the controller inherits the host's own URL helpers
+      # the way a controller the host wrote does.
+      app.config.to_prepare { require 'crest/cards_controller' }
+    end
+  end
+end

data/lib/crest/routes.rb

@@ -0,0 +1,14 @@
+module Crest
+  # Extends the config/routes.rb DSL, so `crest` draws a contact card wherever a host puts it.
+  module Routes
+    # Draws a GET at the path the host names, answered by the card the initializer describes.
+    # The host names it because the filename is the app's own name, and the helper is named after
+    # the file -- `crest 'houseaccount.vcf'` gives `houseaccount_vcf_path`. A route rather than an
+    # engine to mount, so the line may sit inside a `scope` or a `constraints` the host wrote.
+    # @param path [String] name the card is downloaded under, `.vcf` and all.
+    # @return [void]
+    def crest(path)
+      get path, to: 'crest/cards#show', as: path.parameterize(separator: '_')
+    end
+  end
+end

data/lib/crest/version.rb

@@ -0,0 +1,4 @@
+module Crest
+  # The version of this gem, as RubyGems knows it.
+  VERSION = '0.1.0'
+end

data/lib/crest.rb

@@ -0,0 +1,24 @@
+require 'crest/error'
+require 'crest/version'
+require 'crest/config'
+require 'crest/card'
+
+# Rails-only from here: the builder above is plain Ruby, and a script may load it on its own.
+require 'crest/railtie' if defined?(Rails)
+
+# A contact card an app hands out, so a text from an unknown number arrives under a name.
+module Crest
+  # @return [Crest::Config] everything a card has to be told about the app around it.
+  def self.config = @config ||= Config.new
+
+  # Yields the configuration, so a host states its own facts in one initializer.
+  # @return [void]
+  def self.configure = yield config
+
+  # Built afresh for every request, since a setting stated as a callable is asked each time.
+  # @return [Crest::Card] card this app is saved under.
+  def self.card
+    Card.new name: config.name, phone: config.phone, url: config.url, email: config.email,
+             org: config.org, photo: config.photo
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: crest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Claudio Baccigalupo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Answers a .vcf route with the vCard a phone offers to save
+email:
+- claudiob@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/crest.rb
+- lib/crest/card.rb
+- lib/crest/cards_controller.rb
+- lib/crest/config.rb
+- lib/crest/error.rb
+- lib/crest/photo.rb
+- lib/crest/railtie.rb
+- lib/crest/routes.rb
+- lib/crest/version.rb
+homepage: https://github.com/claudiob/crest
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/claudiob/crest
+  source_code_uri: https://github.com/claudiob/crest/
+  changelog_uri: https://github.com/claudiob/crest/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/crest
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Hand out a contact card your app is saved under
+test_files: []