abbu 0.4.0 → 0.8.1

data/lib/abbu/exporters/vcard_exporter.rb

@@ -3,6 +3,8 @@
 
 require 'uri'
 
+require_relative 'vcard_document'
+
 module Abbu
   module Exporters
     class VcardExporter
@@ -11,21 +13,21 @@ module Abbu
       end
 
       def to_file(path)
-        File.write(path, generate)
+        File.binwrite(path, generate)
       end
 
       def to_stdout
-        puts generate
+        print generate
       end
 
       private
 
       def generate
-        @contacts.map { |c| vcard_for(c) }.join("\n")
+        @contacts.map { |c| vcard_for(c) }.join
       end
 
       def vcard_for(contact) # rubocop:disable Metrics/MethodLength
-        lines = ['BEGIN:VCARD', 'VERSION:3.0']
+        lines = VcardDocument.new
 
         append_name_fields(lines, contact)
         append_emails(lines, contact)
@@ -39,13 +41,12 @@ module Abbu
         append_notes(lines, contact)
         append_photo(lines, contact)
 
-        lines << 'END:VCARD'
-        lines.join("\n")
+        lines.to_s
       end
 
       def append_name_fields(lines, contact)
-        lines << "FN:#{contact.full_name}"
-        lines << "N:#{name_components(contact).join(';')}"
+        lines << "FN:#{VcardEncoding.text(contact.full_name)}"
+        lines << "N:#{VcardEncoding.structured(name_components(contact))}"
         append_nickname(lines, contact)
         append_company(lines, contact)
         append_title(lines, contact)
@@ -57,25 +58,26 @@ module Abbu
       end
 
       def append_nickname(lines, contact)
-        lines << "NICKNAME:#{contact.nickname}" if contact.nickname
+        lines << "NICKNAME:#{VcardEncoding.text(contact.nickname)}" if contact.nickname
       end
 
       def append_company(lines, contact)
-        lines << "ORG:#{contact.company}" if contact.company
+        lines << "ORG:#{VcardEncoding.text(contact.company)}" if contact.company
       end
 
       def append_title(lines, contact)
-        lines << "TITLE:#{contact.job_title}" if contact.job_title
+        lines << "TITLE:#{VcardEncoding.text(contact.job_title)}" if contact.job_title
       end
 
       def append_phonetic_names(lines, contact)
-        lines << "X-PHONETIC-FIRST-NAME:#{contact.phonetic_first_name}" if contact.phonetic_first_name
-        lines << "X-PHONETIC-MIDDLE-NAME:#{contact.phonetic_middle_name}" if contact.phonetic_middle_name
-        lines << "X-PHONETIC-LAST-NAME:#{contact.phonetic_last_name}" if contact.phonetic_last_name
+        %i[first middle last].each do |part|
+          value = contact.public_send(:"phonetic_#{part}_name")
+          lines << "X-PHONETIC-#{part.upcase}-NAME:#{VcardEncoding.text(value)}" if value
+        end
       end
 
       def append_verification_code(lines, contact)
-        lines << "X-VERIFICATION-CODE:#{contact.verification_code}" if contact.verification_code
+        lines << "X-VERIFICATION-CODE:#{VcardEncoding.text(contact.verification_code)}" if contact.verification_code
       end
 
       def append_photo(lines, contact)
@@ -90,46 +92,47 @@ module Abbu
       end
 
       def append_notes(lines, contact)
-        contact.notes.each { |n| lines << "NOTE:#{n}" }
+        contact.notes.each { |n| lines << "NOTE:#{VcardEncoding.text(n)}" }
       end
 
       def append_emails(lines, contact)
         contact.emails.each do |e|
-          label = e[:label] || 'INTERNET'
-          lines << "EMAIL;TYPE=#{label}:#{e[:address]}"
+          lines.labeled('EMAIL', VcardEncoding.text(e[:address]), e, default_type: 'INTERNET')
         end
       end
 
       def append_phones(lines, contact)
         contact.phones.each do |p|
-          label = p[:label] || 'VOICE'
-          lines << "TEL;TYPE=#{label}:#{p[:number]}"
+          lines.labeled('TEL', VcardEncoding.text(p[:number]), p, default_type: 'VOICE')
         end
       end
 
       def append_addresses(lines, contact)
         contact.addresses.each do |a|
-          label = a[:label] || 'HOME'
-          lines << "ADR;TYPE=#{label}:;;#{a[:street]};#{a[:city]};#{a[:state]};#{a[:zip]};#{a[:country]}"
+          value = VcardEncoding.structured([nil, nil, a[:street], a[:city], a[:state], a[:zip], a[:country]])
+          lines.labeled('ADR', value, a)
         end
       end
 
       def append_urls(lines, contact)
         contact.urls.each do |u|
-          lines << "URL:#{u[:url]}"
+          lines.labeled('URL', VcardEncoding.uri(u[:url]), u)
         end
       end
 
       def append_social_profiles(lines, contact)
         contact.social_profiles.each do |sp|
-          lines << "X-SOCIALPROFILE;TYPE=#{sp[:service]}:#{sp[:username]}"
+          type = sp[:service] ? ";TYPE=#{VcardEncoding.token(sp[:service])}" : ''
+          lines << "X-SOCIALPROFILE#{type}:#{VcardEncoding.text(sp[:username])}"
         end
       end
 
       def append_instant_messages(lines, contact)
         contact.instant_messages.each do |im|
           service = im[:service]&.downcase || 'unknown'
-          lines << "IMPP;TYPE=#{im[:label]}:#{service}:#{im[:address]}"
+          raise ArgumentError, 'IM service must be a URI scheme' unless service.match?(/\A[a-z][a-z0-9+.-]*\z/)
+
+          lines.labeled('IMPP', "#{service}:#{VcardEncoding.uri(im[:address])}", im)
         end
       end
 
@@ -138,12 +141,8 @@ module Abbu
         lines << "X-LUNAR-BDAY:#{format_vcard_date(contact.lunar_birthday)}" if contact.lunar_birthday
         return unless contact.anniversary
 
-        lines << "X-ABDATE;type=pref:#{format_vcard_date(contact.anniversary)}"
-        lines << "X-ABLABEL:#{anniversary_label(contact.anniversary)}"
-      end
-
-      def anniversary_label(anniversary)
-        anniversary[:raw_label] || anniversary[:label] || 'Anniversary'
+        entry = { label: 'Anniversary' }.merge(contact.anniversary.compact)
+        lines.labeled('X-ABDATE', format_vcard_date(contact.anniversary), entry)
       end
 
       def format_vcard_date(date)

data/lib/abbu/group.rb

@@ -0,0 +1,28 @@
+# lib/abbu/group.rb
+# frozen_string_literal: true
+
+require_relative 'query'
+
+module Abbu
+  # A snapshot of an observed SQLite group membership, local to one input file.
+  # Names and record keys are evidence, not globally unique Apple identifiers.
+  class Group
+    attr_reader :record_id, :name, :source, :contacts
+
+    def initialize(record_id:, name:, source:, contacts:)
+      @record_id = record_id
+      @name = name&.dup&.freeze
+      @source = source.transform_values { |value| value&.dup&.freeze }.freeze
+      @contacts = Query.new(contacts.to_a.uniq).freeze
+      freeze
+    end
+
+    def include?(contact)
+      contacts.any? { |member| member.equal?(contact) }
+    end
+
+    def to_h
+      { record_id: record_id, name: name, source: source, contact_count: contacts.count }
+    end
+  end
+end

data/lib/abbu/group_catalog.rb

@@ -0,0 +1,32 @@
+# lib/abbu/group_catalog.rb
+# frozen_string_literal: true
+
+require_relative 'group'
+
+module Abbu
+  class GroupCatalog
+    def initialize(contacts)
+      @contacts = contacts
+    end
+
+    def groups
+      entries_by_key = memberships.group_by { |contact, membership| [contact.source[:path], membership[:record_id]] }
+      groups = entries_by_key.values.map { |entries| build_group(entries) }
+      groups.sort_by { |group| [group.source[:relative_path], group.record_id] }.freeze
+    end
+
+    private
+
+    def memberships
+      @contacts.flat_map do |contact|
+        contact.group_memberships.map { |membership| [contact, membership] }
+      end
+    end
+
+    def build_group(entries)
+      contact, membership = entries.first
+      Group.new(record_id: membership[:record_id], name: membership[:name], source: contact.source,
+                contacts: entries.map(&:first))
+    end
+  end
+end

data/lib/abbu/live_store.rb

@@ -4,6 +4,7 @@
 require 'pathname'
 require 'sqlite3'
 require_relative 'parsers/sqlite_parser'
+require_relative 'source_catalog'
 
 module Abbu
   class LiveStore
@@ -47,6 +48,18 @@ module Abbu
       end
     end
 
+    def sources
+      @sources ||= SourceCatalog.new(database_paths, root_path: @path, contacts: contacts).sources
+    end
+
+    def groups
+      @groups ||= sources.flat_map(&:groups).freeze
+    end
+
+    def groups_for(contact)
+      groups.select { |group| group.include?(contact) }
+    end
+
     private
 
     def validate!

data/lib/abbu/parsers/sqlite_parser.rb

@@ -105,12 +105,14 @@ module Abbu
 
       def groups_for(db, record_id)
         query = <<-SQL
-          SELECT g.ZFIRSTNAME
+          SELECT g.Z_PK, g.ZFIRSTNAME
           FROM Z_ABCDCONTACTGROUP j
           JOIN ZABCDRECORD g ON j.Z_GROUP = g.Z_PK
           WHERE j.Z_CONTACT = ?
         SQL
-        optional_rows(db, record_id, 'Z_ABCDCONTACTGROUP', query).map { |row| row['ZFIRSTNAME'] }
+        optional_rows(db, record_id, 'Z_ABCDCONTACTGROUP', query).map do |row|
+          { record_id: row['Z_PK'], name: row['ZFIRSTNAME'] }
+        end
       end
 
       def urls_for(db, record_id)
@@ -237,7 +239,8 @@ module Abbu
         contact.emails           = emails_for(db, record_id)
         contact.phones           = phones_for(db, record_id)
         contact.addresses        = addresses_for(db, record_id)
-        contact.groups           = groups_for(db, record_id)
+        contact.group_memberships = groups_for(db, record_id)
+        contact.groups           = contact.group_memberships.map { |membership| membership[:name] }
         contact.urls             = urls_for(db, record_id)
         contact.notes            = notes_for(db, record_id)
         contact.related_names    = related_names_for(db, record_id)

data/lib/abbu/query.rb

@@ -1,6 +1,8 @@
 # lib/abbu/query.rb
 # frozen_string_literal: true
 
+require_relative 'timestamp_range'
+
 module Abbu
   class Query
     include Enumerable
@@ -49,6 +51,23 @@ module Abbu
       @contacts.dup
     end
 
+    def in_group(group)
+      self.class.new(select { |contact| group.include?(contact) })
+    end
+
+    def modified_since(value)
+      date_range(:modified_at, since: value)
+    end
+
+    def created_since(value)
+      date_range(:created_at, since: value)
+    end
+
+    def date_range(field, since: nil, before: nil)
+      range = TimestampRange.new(field, since: since, before: before)
+      self.class.new(select { |contact| range.include?(contact.public_send(field)) })
+    end
+
     private
 
     def matches_criteria?(contact, criteria)

data/lib/abbu/source.rb

@@ -0,0 +1,53 @@
+# lib/abbu/source.rb
+# frozen_string_literal: true
+
+require_relative 'group_catalog'
+require_relative 'query'
+
+module Abbu
+  # An observed input container, not an inferred Apple account or provider.
+  # Metadata and membership are frozen; contacts retain their existing mutability.
+  class Source
+    attr_reader :path, :relative_path, :kind, :identifier, :files, :contacts, :group_names, :groups
+
+    def initialize(path:, relative_path:, identifier:, files:, contacts:)
+      @path = copy_string(path)
+      @relative_path = copy_string(relative_path)
+      @identifier = copy_string(identifier)
+      @kind = identifier.nil? ? 'root' : 'source'
+      @files = snapshot_files(files)
+      @contacts = Query.new(contacts.to_a.dup).freeze
+      @group_names = snapshot_group_names
+      @groups = GroupCatalog.new(@contacts).groups
+      freeze
+    end
+
+    # No currently supported evidence identifies an account provider.
+    def provider
+      nil
+    end
+
+    def groups_for(contact)
+      groups.select { |group| group.include?(contact) }
+    end
+
+    def to_h
+      { path: path, relative_path: relative_path, kind: kind, identifier: identifier,
+        provider: provider, files: files, contact_count: contacts.count, group_names: group_names }
+    end
+
+    private
+
+    def copy_string(value)
+      value&.dup&.freeze
+    end
+
+    def snapshot_files(files)
+      files.map { |file| file.transform_values { |value| copy_string(value) }.freeze }.freeze
+    end
+
+    def snapshot_group_names
+      @contacts.flat_map(&:groups).compact.uniq.sort.map { |name| copy_string(name) }.freeze
+    end
+  end
+end

data/lib/abbu/source_catalog.rb

@@ -0,0 +1,32 @@
+# lib/abbu/source_catalog.rb
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'source'
+require_relative 'utils/source_descriptor'
+
+module Abbu
+  # Internal adapter over the same file descriptors used by the parsers.
+  class SourceCatalog
+    def initialize(paths, root_path:, contacts:)
+      @root_path = Pathname.new(root_path).expand_path
+      @files = paths.map { |path| Utils::SourceDescriptor.new(path, root_path: root_path).to_h }
+                    .sort_by { |file| file.fetch(:relative_path) }
+      @contacts_by_path = contacts.group_by { |contact| contact.source&.fetch(:path, nil) }
+    end
+
+    def sources
+      @files.group_by { |file| file.fetch(:identifier) }.map do |identifier, files|
+        relative_path = identifier.nil? ? '.' : "Sources/#{identifier}"
+        Source.new(path: @root_path.join(relative_path).to_s, relative_path: relative_path,
+                   identifier: identifier, files: files, contacts: contacts_for(files))
+      end.sort_by(&:relative_path).freeze
+    end
+
+    private
+
+    def contacts_for(files)
+      files.flat_map { |file| @contacts_by_path.fetch(file.fetch(:path), []) }
+    end
+  end
+end

data/lib/abbu/timestamp_range.rb

@@ -0,0 +1,40 @@
+# lib/abbu/timestamp_range.rb
+# frozen_string_literal: true
+
+require 'date'
+
+module Abbu
+  # Internal filter over observed timestamps, never a claim about human edits.
+  class TimestampRange
+    FORMAT = /\A\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)\z/
+
+    def initialize(field, since: nil, before: nil)
+      raise ArgumentError, 'field must be :created_at or :modified_at' unless %i[created_at modified_at].include?(field)
+      raise ArgumentError, 'at least one timestamp bound is required' if since.nil? && before.nil?
+
+      @since = parse(since) unless since.nil?
+      @before = parse(before) unless before.nil?
+      validate_order
+    end
+
+    def include?(value)
+      !value.nil? && (@since.nil? || value >= @since) && (@before.nil? || value < @before)
+    end
+
+    private
+
+    def validate_order
+      raise ArgumentError, 'since must be earlier than before' if @since && @before && @since >= @before
+    end
+
+    def parse(value)
+      return value if value.is_a?(Time)
+
+      unless value.is_a?(String) && FORMAT.match?(value)
+        raise ArgumentError, 'timestamp must be a Time or ISO 8601 datetime with explicit timezone'
+      end
+
+      DateTime.iso8601(value, Date::GREGORIAN).to_time
+    end
+  end
+end

data/lib/abbu/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Abbu
-  VERSION = '0.4.0'
+  VERSION = '0.8.1'
 end

data/lib/abbu.rb

@@ -9,6 +9,7 @@ require_relative 'abbu/archive'
 require_relative 'abbu/live_store'
 require_relative 'abbu/query'
 require_relative 'abbu/schema_inspector'
+require_relative 'abbu/source'
 require_relative 'abbu/parsers/sqlite_parser'
 require_relative 'abbu/parsers/plist_parser'
 require_relative 'abbu/exporters/csv_exporter'

data/sig/group.rbs

@@ -0,0 +1,36 @@
+# sig/group.rbs
+module Abbu
+  class Contact
+    attr_accessor group_memberships: Array[{ record_id: Integer, name: String? }]
+  end
+
+  class Group
+    attr_reader record_id: Integer
+    attr_reader name: String?
+    attr_reader source: Hash[Symbol, String?]
+    attr_reader contacts: Query
+    def initialize: (record_id: Integer, name: String?, source: Hash[Symbol, String?],
+                     contacts: Enumerable[Contact]) -> void
+    def include?: (Contact contact) -> bool
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Source
+    attr_reader groups: Array[Group]
+    def groups_for: (Contact contact) -> Array[Group]
+  end
+
+  class Archive
+    def groups: () -> Array[Group]
+    def groups_for: (Contact contact) -> Array[Group]
+  end
+
+  class LiveStore
+    def groups: () -> Array[Group]
+    def groups_for: (Contact contact) -> Array[Group]
+  end
+
+  class Query
+    def in_group: (Group group) -> Query
+  end
+end

data/sig/query.rbs

@@ -0,0 +1,21 @@
+# sig/query.rbs
+module Abbu
+  class Contact
+  end
+
+  class Query
+    include Enumerable[Contact]
+
+    def initialize: (Enumerable[Contact] contacts) -> void
+    def each: () { (Contact) -> void } -> Array[Contact]
+            | () -> Enumerator[Contact, Array[Contact]]
+    def where: (Hash[Symbol, untyped] criteria) -> Query
+    def search: (String term) -> Query
+    def find_by_email: (String email) -> Query
+    def find_by_phone: (String phone) -> Query
+    def to_a: () -> Array[Contact]
+    def created_since: (Time | String value) -> Query
+    def modified_since: (Time | String value) -> Query
+    def date_range: (:created_at | :modified_at field, ?since: Time | String | nil, ?before: Time | String | nil) -> Query
+  end
+end

data/sig/source.rbs

@@ -0,0 +1,25 @@
+# sig/source.rbs
+module Abbu
+  class Source
+    attr_reader path: String
+    attr_reader relative_path: String
+    attr_reader kind: String
+    attr_reader identifier: String?
+    attr_reader files: Array[Hash[Symbol, String?]]
+    attr_reader contacts: Query
+    attr_reader group_names: Array[String]
+
+    def initialize: (path: String, relative_path: String, identifier: String?,
+                     files: Array[Hash[Symbol, String?]], contacts: Enumerable[Contact]) -> void
+    def provider: () -> nil
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Archive
+    def sources: () -> Array[Source]
+  end
+
+  class LiveStore
+    def sources: () -> Array[Source]
+  end
+end

data/sig/vcard_exporter.rbs

@@ -0,0 +1,10 @@
+# sig/vcard_exporter.rbs
+module Abbu
+  module Exporters
+    class VcardExporter
+      def initialize: (Enumerable[Contact] contacts) -> void
+      def to_file: (String | Pathname path) -> Integer
+      def to_stdout: () -> nil
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: abbu
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Stan Carver II
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
@@ -220,8 +220,11 @@ files:
 - README.md
 - bin/abbu
 - docs/ABBU.md
+- docs/API_STABILITY.md
 - docs/CHANGELOG.md
 - docs/CONTRIBUTING.md
+- docs/FORMAT_COMPATIBILITY.md
+- docs/RELEASING.md
 - docs/TODO.md
 - examples/deduplicate_contacts.rb
 - examples/export_to_api.rb
@@ -236,7 +239,11 @@ files:
 - lib/abbu/diagnostic.rb
 - lib/abbu/exporters/csv_exporter.rb
 - lib/abbu/exporters/json_exporter.rb
+- lib/abbu/exporters/vcard_document.rb
+- lib/abbu/exporters/vcard_encoding.rb
 - lib/abbu/exporters/vcard_exporter.rb
+- lib/abbu/group.rb
+- lib/abbu/group_catalog.rb
 - lib/abbu/image_extractor.rb
 - lib/abbu/live_store.rb
 - lib/abbu/parse_error.rb
@@ -244,12 +251,19 @@ files:
 - lib/abbu/parsers/sqlite_parser.rb
 - lib/abbu/query.rb
 - lib/abbu/schema_inspector.rb
+- lib/abbu/source.rb
+- lib/abbu/source_catalog.rb
+- lib/abbu/timestamp_range.rb
 - lib/abbu/utils/contact_identity.rb
 - lib/abbu/utils/deduplicator.rb
 - lib/abbu/utils/image_resolver.rb
 - lib/abbu/utils/label_normalizer.rb
 - lib/abbu/utils/source_descriptor.rb
 - lib/abbu/version.rb
+- sig/group.rbs
+- sig/query.rbs
+- sig/source.rbs
+- sig/vcard_exporter.rbs
 - tasks/abbu.rake
 homepage: https://github.com/scarver2/abbu
 licenses: