kamisaku 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82cbb110627e0fb58ce9d9dee310d46ee9339ad54728676ed0f4b010ad664c5e
-  data.tar.gz: e2f4b74163a6febdf4576be058a64bf051f86e59b08a2679f38251f840eda83e
+  metadata.gz: '0307528fa9400ae092638a768482af0a290b9f7e65f0ca8fcccfa501493eeb92'
+  data.tar.gz: bec81b49d0f9a635ad59dcfde08f718a5f8ab5471fa5d9c23eaf37dd2a3789e5
 SHA512:
-  metadata.gz: 5a2c519714481d39b458e56cb1865b20fdf0c3133f856013692b6bd19c5fb43b7ede85eb1fb59d07cbcbcaccd4524933bfe92c3656e032ec27e6da6757787ba0
-  data.tar.gz: 02a8381a44b6f732bf86beb985fea8d9bd383c960ce640793bd23faaf1e38e57b28e887da8c0d2060f7cc51502575e3b2f1585f87a051f0b21d47ed181b1d546
+  metadata.gz: '0738241ce36d4fb6e43439a35e39614ac935e922247cfb91e87dc3e236b6897f105feee6d827e3341f19286344935e7c37ea19e4705b6c7eb5187c6758049c6f'
+  data.tar.gz: 0525b51569873f87984eadd9c779b3ac0254250c541e3fbf6cb37e0f14a746ac3866e2024911f94727f6af40f58afd0758ef6c5faddb915534328e638fa0b27f

data/CHANGELOG.md

@@ -13,6 +13,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.4.0] - 2025.06.09
+
+### Added
+- Added new `birthday_invitation` schema type for Birthday Invitation PDF generations
+
+### Changed
+- Updated the CLI tool to accept `category` to generate specific PDF
+
+## [0.3.4] - 2025.06.06
+
+### Added
+- Add new templates `chromatic`, `gradient`, `meridian`, `prism`, and `zenith`
+
+### Changed
+- Update paper template
+
+
 ## [0.3.3] - 2025.06.01
 
 ### Changed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kamisaku (0.3.3)
+    kamisaku (0.4.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,6 @@
 # 📃 Kamisaku
 
-*Build a CV PDF from a yaml text file.*
+*Build resume PDF from a yaml text file.*
 
 🚀 See it in action at [https://kamisaku.sinaru.com/](https://kamisaku.sinaru.com/?utm_source=github).
 
@@ -11,7 +11,7 @@
 See [examples](/examples) directory for sample generated PDF files based of [templates](/lib/templates).
 
 ## Templates
-For a list of templates availble for CV generation, check the [examples](/examples) directory where each directory name is a template name.
+For a list of templates availble for PDF generation, check the [examples](/examples) directory where each directory name is a template name.
 
 ## Installation
 
@@ -42,64 +42,9 @@ $ gem install kamisaku
 
 ## Usage
 
-First we need to have a `yaml` file or a string with the CV data. The gem supports the following sections.
-
-```yaml
-version: 1
-profile:
-  name: # Your name
-  title: # Your current job title
-  about: # Some sleek details about your experience
-
-contact:
-  github: # Github username
-  mobile: # Mobile number
-  email: # email address
-  linkedin: # Linkedin username
-  location:
-    country: # country name
-    city: # city name
-
-skills:
-  - area: # specific skill area you are specialized in
-    items:
-      - # sub item such as a technology you have the skill in under the specialized area
-
-experiences:
-  - title: # job title
-    organisation: # Name of the place you worked
-    location:
-      city: # city name
-      country: # country name
-    from:
-      month: # month number that you started
-      year: # year number that you started
-  # if following is not given, it is assumed you are still working
-    to:
-      month: # month number that you stopped
-      year: # year number that you stopped
-    skills:
-      - # a short name for a specialized skilled you gained
-    achievements:
-      - # Things you have achieved or did
-
-education:
-  - institute: # name of the place you studied
-    location:
-      city: # city name
-      country: # country name
-    qualification: # name of the degree/diploma qualification
-    field: # name of the field such as Computer Science
-    from:
-      month: # month number that you started
-      year: # year number that you started
-    # if following is not given, it is assumed you are still studying
-    to:
-      month: # month number that you stopped
-      year: # year number that you stopped
-    achievements:
-      - # Things you have achieved or did
-```
+First we need to have a `yaml` file or a string with the correct schema data structure for the type of the PDF you are generating.
+
+For the list of schemas, check `lib/schema` folder. E.g. For resume it is `lib/schema/resume/schema.yml`.
 
 ## Generating PDF
 
@@ -108,13 +53,14 @@ education:
 Once you have the YAML text file, feed it into the `bin/console` and specify the output location.
 
 ```bash
-bin/console -c examples/paper/john_doe.yml -o examples/paper/john_doe.pdf  -t paper
+bin/console -c examples/john_doe.yml -o examples/paper/john_doe.pdf -k resume -t paper
 ```
 
 #### Bash options
 
 - `-c` the YAML file
 - `-o` output location for the PDF file including the name
+- `-k` the type of document you want to generate
 - `-t` template to use
 
 ### Using `PDF` class
@@ -125,9 +71,9 @@ yaml_str = "..."
 # Create a hash
 content_hash = Kamisaku::Helpers.yaml_str_to_content_hash(yaml_str)
 # Validate the hash is correct. If there is any issue, it will raise a ` Kamisaku::Error ` exception.
-Kamisaku::ContentValidator.new(content_hash:).validate!
+Kamisaku::BaseContentValidator.new(content_hash:).validate!
 # create a pdf instance
-pdf = Kamisaku::PDF.new(content_hash:, template: "paper")
+pdf = Kamisaku::PDF.new(content_hash:, category: "resume", template: "paper")
 # create the PDF at given path
 pdf.write_to('/path/to/generated_file.pdf')
 ```
@@ -136,7 +82,25 @@ pdf.write_to('/path/to/generated_file.pdf')
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Create or Update a template
+
+To a new template, create a folder with template name at `lib/templates`. Additionally add the template name to `Kamisaku::TemplateHelpers::TEMPLATES` list.
+
+Inside this folder, create `template.html.erb`.
+
+The template will be exposed to a Ruby hash variable called `data`. This data represent the data in the YAML file as a hash. 
+So you can use the Ruby hash methods to access and render the values.
+
+In addition, the template helper methods defined at `lib/kamisaku/template_helpers.rb` will also be available to use directly. 
+
+To test and build the template, you can run `scripts/rebuild_examples.rb -t <name of new template>`. This will create the PDF using the `lib/schema/example.yml`
+and place it in `examples/` folder.
+
+### Releasing a new gem version
+
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/kamisaku/arg_parser.rb

@@ -20,6 +20,10 @@ module Kamisaku
           options[:pdf_file] = pdf_file
         end
 
+        parser.on("-k", "--category CATEGORY", "Provide the TEMPLATE name") do |category|
+          options[:category] = category
+        end
+
         parser.on("-t", "--template TEMPLATE", "Provide the TEMPLATE name") do |template|
           options[:template] = template
         end

data/lib/kamisaku/cli_runner.rb

@@ -6,9 +6,9 @@ module Kamisaku
       raise Kamisaku::Error.new "YAML file does not exist" unless File.exist?(yaml_file)
 
       yaml_string = File.read(yaml_file)
-      pdf = PDF.new(content_hash: Helpers.yaml_str_to_content_hash(yaml_string), template: options[:template])
+      pdf = PDF.new(content_hash: Helpers.yaml_str_to_content_hash(yaml_string), category: options[:category], template: options[:template])
       pdf.write_to(options[:pdf_file])
-      pdf.generate_html(options[:html_output]) if options[:html_output]
+      pdf.write_to_html_file(options[:html_output]) if options[:html_output]
     end
   end
 end

data/lib/kamisaku/content_validators/base_content_validator.rb

@@ -0,0 +1,14 @@
+module Kamisaku
+  class BaseContentValidator
+    attr_reader :content_hash
+    alias_method :data, :content_hash
+
+    def initialize(content_hash:)
+      @content_hash = content_hash
+    end
+
+    def validate!
+      # Override by child class
+    end
+  end
+end

data/lib/kamisaku/content_validators/birthday_invitation_content_validator.rb

@@ -0,0 +1,218 @@
+module Kamisaku
+  class BirthdayInvitationContentValidator < BaseContentValidator
+    TEMPLATES = %(
+      dino
+    ).freeze
+
+    def validate!
+      validate_party_details
+      validate_venue
+      validate_contact_info
+      validate_rsvp
+      validate_special_instructions if data[:special_instructions]
+      validate_activities if data[:activities]
+    end
+
+    private
+
+    def validate_party_details
+      raise Error, "Missing party_details" unless data[:party_details]
+      raise Error, "party_details must be a hash" unless data[:party_details].is_a?(Hash)
+
+      required_fields = %i[person_name age date start_time]
+      allowed_fields = %i[person_name age date start_time end_time theme]
+      party_fields = data[:party_details].keys
+
+      unless party_fields.all? { |field| allowed_fields.include?(field) }
+        raise Error, "party_details contains invalid fields"
+      end
+
+      required_fields.each do |field|
+        unless party_fields.include?(field)
+          raise Error, "party_details missing required field '#{field}'"
+        end
+      end
+
+      validate_string_field(data[:party_details][:person_name], "party_details", "person_name")
+      validate_integer_field(data[:party_details][:age], "party_details", "age")
+      validate_date(data[:party_details][:date], "party_details")
+      validate_string_field(data[:party_details][:start_time], "party_details", "start_time")
+
+      if data[:party_details][:end_time]
+        validate_string_field(data[:party_details][:end_time], "party_details", "end_time")
+      end
+
+      if data[:party_details][:theme]
+        validate_string_field(data[:party_details][:theme], "party_details", "theme")
+      end
+    end
+
+    def validate_venue
+      raise Error, "Missing venue" unless data[:venue]
+      raise Error, "venue must be a hash" unless data[:venue].is_a?(Hash)
+
+      required_fields = %i[address]
+      allowed_fields = %i[name address additional_instructions]
+      venue_fields = data[:venue].keys
+
+      unless venue_fields.all? { |field| allowed_fields.include?(field) }
+        raise Error, "venue contains invalid fields"
+      end
+
+      required_fields.each do |field|
+        unless venue_fields.include?(field)
+          raise Error, "venue missing required field '#{field}'"
+        end
+      end
+
+      validate_string_field(data[:venue][:address], "venue", "address")
+
+      if data[:venue][:name]
+        validate_string_field(data[:venue][:name], "venue", "name")
+      end
+
+      if data[:venue][:additional_instructions]
+        validate_string_field(data[:venue][:additional_instructions], "venue", "additional_instructions")
+      end
+    end
+
+    def validate_contact_info
+      raise Error, "Missing contact_info" unless data[:contact_info]
+      raise Error, "contact_info must be a hash" unless data[:contact_info].is_a?(Hash)
+
+      required_fields = %i[host_name phone]
+      allowed_fields = %i[host_name phone email]
+      contact_fields = data[:contact_info].keys
+
+      unless contact_fields.all? { |field| allowed_fields.include?(field) }
+        raise Error, "contact_info contains invalid fields"
+      end
+
+      required_fields.each do |field|
+        unless contact_fields.include?(field)
+          raise Error, "contact_info missing required field '#{field}'"
+        end
+      end
+
+      validate_string_field(data[:contact_info][:host_name], "contact_info", "host_name")
+      validate_string_field(data[:contact_info][:phone], "contact_info", "phone")
+
+      if data[:contact_info][:email]
+        validate_string_field(data[:contact_info][:email], "contact_info", "email")
+      end
+    end
+
+    def validate_rsvp
+      raise Error, "Missing rsvp" unless data[:rsvp]
+      raise Error, "rsvp must be a hash" unless data[:rsvp].is_a?(Hash)
+
+      required_fields = %i[deadline method contact]
+      rsvp_fields = data[:rsvp].keys
+
+      unless rsvp_fields.all? { |field| required_fields.include?(field) }
+        raise Error, "rsvp contains invalid fields"
+      end
+
+      required_fields.each do |field|
+        unless rsvp_fields.include?(field)
+          raise Error, "rsvp missing required field '#{field}'"
+        end
+      end
+
+      validate_date(data[:rsvp][:deadline], "rsvp")
+      validate_string_field(data[:rsvp][:method], "rsvp", "method")
+      validate_string_field(data[:rsvp][:contact], "rsvp", "contact")
+    end
+
+    def validate_special_instructions
+      raise Error, "special_instructions must be a hash" unless data[:special_instructions].is_a?(Hash)
+
+      allowed_fields = %i[what_to_bring dress_code food_allergies_note gift_preferences parking_info weather_backup]
+      special_fields = data[:special_instructions].keys
+
+      unless special_fields.all? { |field| allowed_fields.include?(field) }
+        raise Error, "special_instructions contains invalid fields"
+      end
+
+      data[:special_instructions].each do |field, value|
+        validate_string_field(value, "special_instructions", field.to_s)
+      end
+    end
+
+    def validate_activities
+      raise Error, "activities must be a hash" unless data[:activities].is_a?(Hash)
+
+      allowed_fields = %i[main_activities entertainment]
+      activities_fields = data[:activities].keys
+
+      unless activities_fields.all? { |field| allowed_fields.include?(field) }
+        raise Error, "activities contains invalid fields"
+      end
+
+      if data[:activities][:main_activities]
+        validate_array_of_strings(data[:activities][:main_activities], "activities", "main_activities")
+      end
+
+      if data[:activities][:entertainment]
+        validate_string_field(data[:activities][:entertainment], "activities", "entertainment")
+      end
+    end
+
+    def validate_date(date, section)
+      raise Error, "#{section}: date must be a hash" unless date.is_a?(Hash)
+
+      required_fields = %i[day month year]
+      date_fields = date.keys
+
+      unless date_fields.all? { |field| required_fields.include?(field) }
+        raise Error, "#{section}: date contains invalid fields"
+      end
+
+      required_fields.each do |field|
+        unless date_fields.include?(field)
+          raise Error, "#{section}: date missing required field '#{field}'"
+        end
+        validate_integer_field(date[field], section, "date.#{field}")
+      end
+
+      validate_day_range(date[:day], section)
+      validate_month_range(date[:month], section)
+    end
+
+    def validate_string_field(value, section, field)
+      unless value.is_a?(String)
+        raise Error, "#{section}: field '#{field}' must be a string"
+      end
+    end
+
+    def validate_integer_field(value, section, field)
+      unless value.is_a?(Integer)
+        raise Error, "#{section}: field '#{field}' must be an integer"
+      end
+    end
+
+    def validate_array_of_strings(value, section, field)
+      unless value.is_a?(Array)
+        raise Error, "#{section}: field '#{field}' must be an array"
+      end
+
+      value.each do |item|
+        unless item.is_a?(String)
+          raise Error, "#{section}: each item in '#{field}' must be a string"
+        end
+      end
+    end
+
+    def validate_day_range(day, section)
+      unless day.between?(1, 31)
+        raise Error, "#{section}: day must be between 1-31"
+      end
+    end
+
+    def validate_month_range(month, section)
+      unless month.between?(1, 12)
+        raise Error, "#{section}: month must be between 1-12"
+      end
+    end
+  end
+end

data/lib/kamisaku/{content_validator.rb → content_validators/resume_content_validator.rb}

@@ -1,11 +1,14 @@
 module Kamisaku
-  class ContentValidator
-    attr_reader :content_hash
-    alias_method :data, :content_hash
-
-    def initialize(content_hash:)
-      @content_hash = content_hash
-    end
+  class ResumeContentValidator < Kamisaku::BaseContentValidator
+    TEMPLATES = %w[
+      paper
+      sleek
+      zenith
+      meridian
+      prism
+      gradient
+      chromatic
+    ].freeze
 
     def validate!
       validate_version
@@ -25,14 +28,15 @@ module Kamisaku
       raise Error, "Missing profile" unless data[:profile]
       raise Error, "Profile must be a hash" unless data[:profile].is_a?(Hash)
 
-      allowed_fields = %i[name title about]
+      allowed_fields = %i[name title about photo_url]
+      required_fields = %i[name title about]
       profile_fields = data[:profile].keys
 
       unless profile_fields.all? { |field| allowed_fields.include?(field) }
         raise Error, "Profile contains invalid fields"
       end
 
-      unless profile_fields.size == allowed_fields.size
+      unless required_fields.all? { |field| profile_fields.include?(field) }
         raise Error, "Profile must contain exactly the fields: #{allowed_fields.join(", ")}"
       end
 
@@ -41,6 +45,19 @@ module Kamisaku
           raise Error, "Profile field '#{field}' must be a string"
         end
       end
+
+      if data[:profile][:photo_url]
+        validate_photo_url(data[:profile][:photo_url])
+      end
+    end
+
+    def validate_photo_url(photo_url)
+      raise Error, "Profile field '#{field}' must be a string" unless photo_url.is_a?(String)
+
+      valid_url_regex = /\Ahttps?:\/\/.+\.(jpg|jpeg)\z/i
+      unless valid_url_regex.match?(photo_url)
+        raise Error, "Invalid photo_url. It must be an HTTP/HTTPS URL ending with .jpg or .jpeg"
+      end
     end
 
     def validate_contact
@@ -87,7 +104,7 @@ module Kamisaku
       data[:skills].each do |skill|
         raise Error, "Each skill must be a hash" unless skill.is_a?(Hash)
 
-        allowed_fields = %i[area items]
+        allowed_fields = %i[name items]
         skill_fields = skill.keys
 
         unless skill_fields.all? { |field| allowed_fields.include?(field) }
@@ -98,7 +115,7 @@ module Kamisaku
           raise Error, "Skills section: Skill missing required field '#{field}'" unless skill_fields.include?(field)
         end
 
-        raise Error, "Skills section: Skill field 'area' must be a string" unless skill[:area].is_a?(String)
+        raise Error, "Skills section: Skill field 'name' must be a string" unless skill[:name].is_a?(String)
         raise Error, "Skills section: Skill field 'items' must be an array" unless skill[:items].is_a?(Array)
 
         skill[:items].each do |item|

data/lib/kamisaku/html_builder.rb

@@ -2,13 +2,14 @@ require "erb"
 
 module Kamisaku
   class HtmlBuilder
-    attr_reader :content_hash, :template
+    attr_reader :content_hash, :category, :template
     alias_method :data, :content_hash
 
     include TemplateHelpers
 
-    def initialize(content_hash, template)
+    def initialize(content_hash, category, template)
       @content_hash = content_hash
+      @category = category
       @template = template
     end
 
@@ -20,7 +21,7 @@ module Kamisaku
     private
 
     def template_html
-      path = File.join(File.dirname(__FILE__), "/../templates/#{template}/template.html.erb")
+      path = File.join(File.dirname(__FILE__), "/../templates/#{category}/#{template}/template.html.erb")
       File.read(path)
     end
   end

data/lib/kamisaku/pdf.rb

@@ -1,13 +1,23 @@
+require "tempfile"
+
 module Kamisaku
   class PDF
-    attr_reader :content_hash, :template
+    attr_reader :content_hash, :category, :template
+
+    CONTENT_VALIDATOR_MAP = {
+      resume: ResumeContentValidator,
+      birthday_invitation: BirthdayInvitationContentValidator
+    }
 
-    def initialize(content_hash:, template: nil)
+    def initialize(content_hash:, category:, template:)
       @content_hash = content_hash
-      @template = template || "sleek"
-      ContentValidator.new(content_hash:).validate!
+      @category = category
+      @template = template
       raise Error, "Invalid template name '#{template}'" unless template.is_a?(String)
-      raise Error, "Invalid template name '#{template}'" unless TemplateHelpers::TEMPLATES.include? @template
+      validator_klass = CONTENT_VALIDATOR_MAP[category.to_sym]
+      raise Error, "Invalid template name '#{category}'" unless validator_klass
+      validator_klass.new(content_hash:).validate!
+      raise Error, "Invalid template name '#{template}'" unless validator_klass::TEMPLATES.include?(template)
     end
 
     def write_to(pdf_location)
@@ -17,7 +27,7 @@ module Kamisaku
       end
     end
 
-    def generate_html(html_location)
+    def write_to_html_file(html_location)
       html_file { |file_path| FileUtils.cp(file_path, html_location) }
     end
 
@@ -42,13 +52,8 @@ module Kamisaku
     def html
       return @html if defined? @html
 
-      builder = HtmlBuilder.new(content_hash, template)
+      builder = HtmlBuilder.new(content_hash, category, template)
       @html = builder.html
     end
-
-    def template_html
-      path = File.join(File.dirname(__FILE__), "/../templates/#{template}/template.html.erb")
-      File.read(path)
-    end
   end
 end

data/lib/kamisaku/template_helpers.rb

@@ -2,8 +2,6 @@ require "date"
 
 module Kamisaku
   module TemplateHelpers
-    TEMPLATES = %w[paper sleek].freeze
-
     def month_name(month_int)
       return "" if month_int.nil?
 

data/lib/kamisaku/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kamisaku
-  VERSION = "0.3.3"
+  VERSION = "0.4.0"
 end

data/lib/kamisaku.rb

@@ -2,9 +2,11 @@ require_relative "kamisaku/version"
 require_relative "kamisaku/errors"
 require_relative "kamisaku/helpers"
 require_relative "kamisaku/arg_parser"
-require_relative "kamisaku/pdf"
 require_relative "kamisaku/chrome_runner"
 require_relative "kamisaku/cli_runner"
 require_relative "kamisaku/template_helpers"
 require_relative "kamisaku/html_builder"
-require_relative "kamisaku/content_validator"
+require_relative "kamisaku/content_validators/base_content_validator"
+require_relative "kamisaku/content_validators/resume_content_validator"
+require_relative "kamisaku/content_validators/birthday_invitation_content_validator"
+require_relative "kamisaku/pdf"