holivia 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83d3ab262bb3fc4381d4ca420e6186ef577ce8e40db802b0658209e2ea0599b5
-  data.tar.gz: 36813fba6ea7c7cdb25d6b5cbfc97905226959e956fa02a146c9d60a54357898
+  metadata.gz: 88e7b483f29ede5b8d719e09e0e64014979b01fbe4f46e3476131d5f04cf6dd4
+  data.tar.gz: 51142c7c75c2917c065e7eb99b9c5162d3c08e435722acdf2f532bcc4b17d2e7
 SHA512:
-  metadata.gz: 36d0c89c7d469290018d121ada800c8bf4da4fcc6af6918930c5907c283786b5aded11979050a0f6ef9fb19c127bdebb789e3b014eb09c842c568eb404421f05
-  data.tar.gz: 8e9086a2a046deec0170ec502391c8cda726963933d8597159aa98ce498e21d88a0e6aebe059606ae07387cad8655be6f88449ed3035cee1d6a161dfff316044
+  metadata.gz: 2b35a23633a3f1fd43dd849297c49f2bf836d237575ccd797fdd63274743b06cabd66a8c082cb82b14992270cb1f5c1048c0fce32cd7f8c1c12032dca529ae9e
+  data.tar.gz: 4fd44133555a0453e2e21b4daad51d1ba5a7e5e42bfba0f8bce98f0b1c245af8bbcc0913a0e74964ed2c690506d12ad3fbee4a15138c52f7bcc2a5478c8aa446

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-05
+
+- Add `holivia appointment video-diagnostics <id>` for appointment video diagnostics
+
 ## [0.5.0] - 2026-05-06
 
 - Add `--state` flag on `selfcare create` and `selfcare update` for AASM-driven lifecycle transitions

data/README.md

@@ -1,43 +1,229 @@
 # Holivia
 
-TODO: Delete this and the text below, and describe your gem
+Ruby client and command-line interface for the Holivia API.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/holivia`. To experiment with that code, run `bin/console` for an interactive prompt.
+The `holivia` executable is primarily used to manage Holivia backoffice data from the terminal: environments, authentication, selfcare content, objectives, and appointment diagnostics.
+
+Coding agents can use [`SKILL.md`](SKILL.md) as a downloadable usage guide for operating this CLI safely.
+
+## Requirements
+
+- Ruby 3.1 or newer
+- A Holivia account with API access
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Install the CLI from RubyGems:
+
+```bash
+gem install holivia
+```
+
+If you want to use the gem from a Ruby application, add it to your bundle:
+
+```bash
+bundle add holivia
+```
+
+After installation, verify the executable is available:
+
+```bash
+holivia version
+```
+
+## Setup
+
+The CLI stores environment configuration in `~/.holivia/config.yml`.
+
+Show the current environment:
+
+```bash
+holivia env
+```
+
+Add an API environment:
+
+```bash
+holivia env add staging --url https://staging.example.com
+```
+
+Switch to an environment:
+
+```bash
+holivia env use staging
+```
+
+List configured environments:
+
+```bash
+holivia env list
+```
+
+Enable debug logging for the current environment when troubleshooting requests:
+
+```bash
+holivia env debug --true
+```
+
+Disable it again with:
+
+```bash
+holivia env debug --false
+```
+
+## Authentication
+
+Log in interactively:
+
+```bash
+holivia login
+```
+
+Or pass credentials directly:
+
+```bash
+holivia login --email user@example.com --password secret
+```
+
+Credentials are stored per environment in `~/.holivia/credentials.<env>.json`. Access tokens are sent as bearer tokens, and the CLI automatically refreshes credentials after a `401` response when a refresh token is available.
+
+Log out and remove stored credentials for the current environment:
+
+```bash
+holivia logout
+```
+
+## Basic Usage
+
+Show all available commands:
+
+```bash
+holivia --help
+```
+
+Discover valid selfcare enum values and item parameters:
+
+```bash
+holivia selfcare schema
+```
+
+List selfcare contents:
+
+```bash
+holivia selfcare index
+```
+
+Show one selfcare content:
+
+```bash
+holivia selfcare show 123
+```
+
+Create a selfcare content from flags:
+
+```bash
+holivia selfcare create \
+  --title "Breathing exercise" \
+  --locale fr \
+  --content-type exercise \
+  --duration 300 \
+  --state draft
+```
+
+Create a full selfcare content tree from JSON:
+
+```bash
+holivia selfcare compose --file examples/compose.json
+```
 
-Install the gem and add to the application's Gemfile by executing:
+You can print a compose template with:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+holivia selfcare compose --example
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Create and update commands also accept JSON from standard input:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+printf '{"title":"Breathing exercise","locale":"fr"}' | holivia selfcare create
 ```
 
-## Usage
+List objectives:
+
+```bash
+holivia objective index
+```
 
-TODO: Write usage instructions here
+Filter objectives by code:
+
+```bash
+holivia objective index --code anxiety
+```
+
+Show video diagnostics for an appointment:
+
+```bash
+holivia appointment video-diagnostics 42
+```
+
+## Files And Uploads
+
+Selfcare create and update commands can upload images with `--image <path>`.
+
+```bash
+holivia selfcare update 123 --image cover.png
+```
+
+Slide item create and update commands can upload audio with `--audio <path>`.
+
+```bash
+holivia selfcare item create --slide-id 456 --item-type AudioItem --audio meditation.mp3
+```
+
+Compose is JSON-only. To attach an image to a composed content tree, update the returned content id afterward with `holivia selfcare update <id> --image <path>`.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run:
+
+```bash
+bin/setup
+```
+
+Run the test suite with:
+
+```bash
+rake spec
+```
+
+Open an interactive console with:
+
+```bash
+bin/console
+```
+
+Install this gem onto your local machine with:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version, update the version number in `lib/holivia/version.rb`, then run:
+
+```bash
+bundle exec rake release
+```
 
-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).
+This creates a git tag, pushes commits and tags, and publishes the `.gem` file to [RubyGems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/holivia. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/holivia/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/Holivia-Team/holivia-ruby.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+## Code Of Conduct
 
-Everyone interacting in the Holivia project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/holivia/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Holivia project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/Holivia-Team/holivia-ruby/blob/master/CODE_OF_CONDUCT.md).

data/SKILL.md

@@ -0,0 +1,339 @@
+# Holivia CLI Skill
+
+Use this skill when you need to operate the Holivia API through the `holivia` command-line tool.
+
+The CLI manages Holivia backoffice data: environments, authentication, selfcare contents, objectives, selfcare-objective associations, and appointment video diagnostics.
+
+## Preconditions
+
+- Ruby 3.1 or newer is available.
+- The CLI is installed with `gem install holivia`, or you are running inside this repository with `bundle exec exe/holivia`.
+- The user has provided the correct Holivia API base URL and account credentials, or they have already authenticated locally.
+
+Use `holivia` in examples below. If working from a checkout before installation, replace it with `bundle exec exe/holivia`.
+
+## Safety Rules
+
+- Never invent API URLs, credentials, IDs, enum values, or content model fields.
+- Never print, store, or commit passwords, access tokens, refresh tokens, or files under `~/.holivia/credentials.*.json`.
+- Prefer interactive `holivia login` when a human can enter credentials. Use `--password` only when the user explicitly provides it for automation.
+- Before creating or updating content, run `holivia selfcare schema` and use its returned enum values and permitted item params as the source of truth.
+- For destructive actions such as `holivia env remove` or `holivia selfcare objective delete`, confirm the target environment and ID first unless the user explicitly requested that exact action.
+- Treat all command output as JSON except informational commands such as `holivia env`, `holivia env list`, `holivia login`, `holivia logout`, `holivia version`, and `holivia --help`.
+
+## Installation
+
+Install the released CLI:
+
+```bash
+gem install holivia
+```
+
+Verify it is available:
+
+```bash
+holivia version
+```
+
+When working from this repository without installing the gem:
+
+```bash
+bundle install
+bundle exec exe/holivia version
+```
+
+## Environment Setup
+
+The CLI stores environment configuration at `~/.holivia/config.yml`.
+
+Show the active environment:
+
+```bash
+holivia env
+```
+
+List environments:
+
+```bash
+holivia env list
+```
+
+Add or update an environment:
+
+```bash
+holivia env add staging --url https://api.example.com
+```
+
+Switch environments:
+
+```bash
+holivia env use staging
+```
+
+Enable request debug logging for troubleshooting:
+
+```bash
+holivia env debug --true
+```
+
+Disable request debug logging:
+
+```bash
+holivia env debug --false
+```
+
+Debug logging may expose request details. Do not enable it in shared logs unless needed.
+
+## Authentication
+
+Credentials are stored per environment at `~/.holivia/credentials.<env>.json`. The CLI sends the access token as a bearer token and refreshes credentials automatically after a `401` response when possible.
+
+Interactive login:
+
+```bash
+holivia login
+```
+
+Non-interactive login:
+
+```bash
+holivia login --email user@example.com --password secret
+```
+
+Logout for the current environment:
+
+```bash
+holivia logout
+```
+
+## Discovery Workflow
+
+Start with help and environment checks:
+
+```bash
+holivia --help
+holivia env
+```
+
+For selfcare content work, always discover the live schema first:
+
+```bash
+holivia selfcare schema
+```
+
+Use the schema response for:
+
+- content types
+- format types
+- item types
+- allowed states
+- objective tiers
+- item-specific permitted params
+
+## Selfcare Content
+
+List contents:
+
+```bash
+holivia selfcare index
+```
+
+Show one content:
+
+```bash
+holivia selfcare show 123
+```
+
+Create a content with flags:
+
+```bash
+holivia selfcare create \
+  --title "Breathing exercise" \
+  --locale fr \
+  --content-type exercise \
+  --duration 300 \
+  --state draft
+```
+
+Update a content:
+
+```bash
+holivia selfcare update 123 --title "Updated title" --state published
+```
+
+Upload or replace an image:
+
+```bash
+holivia selfcare update 123 --image cover.png
+```
+
+Accepted image extensions are `.jpg`, `.jpeg`, `.png`, `.webp`, and `.gif`.
+
+## Compose Workflow
+
+Use compose to create a complete selfcare content tree atomically from JSON.
+
+Print the built-in template:
+
+```bash
+holivia selfcare compose --example
+```
+
+Create from a file:
+
+```bash
+holivia selfcare compose --file payload.json
+```
+
+Create from stdin:
+
+```bash
+printf '{"title":"Example","locale":"fr"}' | holivia selfcare compose
+```
+
+Compose is JSON-only and does not upload files. To attach an image, compose first, read the returned content id, then run:
+
+```bash
+holivia selfcare update <id> --image cover.png
+```
+
+Audio items require file upload and must be added after compose with `holivia selfcare item create`.
+
+## Incremental Content Workflow
+
+Create a content:
+
+```bash
+holivia selfcare create --title "Example" --locale fr --content-type exercise --duration 300 --state draft
+```
+
+Add a format:
+
+```bash
+holivia selfcare format create --selfcare-content-id 123 --format-type text
+```
+
+Add a slide:
+
+```bash
+holivia selfcare slide create --content-format-id 456 --title "Intro" --duration 60
+```
+
+Add a rich text item:
+
+```bash
+holivia selfcare item create --slide-id 789 --item-type RichTextItem --content "Welcome"
+```
+
+Add an audio item:
+
+```bash
+holivia selfcare item create --slide-id 789 --item-type AudioItem --audio meditation.mp3
+```
+
+Accepted audio extensions are `.mp3`, `.mp4`, `.wav`, `.ogg`, `.flac`, `.aac`, `.m4a`, and `.webm`.
+
+Update an item:
+
+```bash
+holivia selfcare item update 321 --content "Updated content"
+```
+
+Most create and update commands accept either flags or JSON from stdin. Prefer JSON for complex payloads.
+
+## Objectives
+
+List objectives:
+
+```bash
+holivia objective index
+```
+
+Paginate objectives:
+
+```bash
+holivia objective index --page 1 --per-page 50
+```
+
+Filter objectives by code:
+
+```bash
+holivia objective index --code anxiety
+```
+
+Show one objective:
+
+```bash
+holivia objective show 123
+```
+
+Objective translated fields are returned in the default locale, currently `fr`.
+
+## Selfcare Objective Associations
+
+List associations:
+
+```bash
+holivia selfcare objective index --selfcare-content-id 123
+```
+
+Show one association:
+
+```bash
+holivia selfcare objective show 456
+```
+
+Associate an objective to selfcare content:
+
+```bash
+holivia selfcare objective create --selfcare-content-id 123 --objective-id 789 --tier main
+```
+
+Update an association tier:
+
+```bash
+holivia selfcare objective update 456 --tier secondary
+```
+
+Delete an association:
+
+```bash
+holivia selfcare objective delete 456
+```
+
+Inline alternative for compose or selfcare update JSON payloads:
+
+```json
+{
+  "objectives": [
+    { "objective_id": 789, "tier": "main" }
+  ]
+}
+```
+
+On update, an empty `objectives` array clears associations. Omitting the key leaves associations unchanged.
+
+## Appointments
+
+Show video diagnostics for an appointment:
+
+```bash
+holivia appointment video-diagnostics 42
+```
+
+## Errors
+
+- `401` means authentication failed or credentials could not be refreshed. Re-run `holivia login` for the active environment.
+- `404` means the requested resource was not found in the active environment.
+- `422` validation errors include structured details such as a payload path and field errors. Use those details to correct the request.
+
+## Agent Checklist
+
+Before making API changes:
+
+- Run `holivia env` and verify the active URL/environment.
+- Run `holivia selfcare schema` before selfcare create/update/compose work.
+- Use existing IDs from list/show commands or explicit user input.
+- Prefer draft states unless the user explicitly requests publishing.
+- Use JSON files or stdin for complex payloads.
+- Summarize created or updated resource IDs after the command succeeds.

data/lib/holivia/cli/help.rb

@@ -49,6 +49,9 @@ module Holivia
           holivia objective show <id>                                  Show one objective
           Translated fields are returned in the default locale (fr).
 
+        Appointments:
+          holivia appointment video-diagnostics <id>  Show video diagnostics for an appointment
+
         Selfcare Content Objectives:
           holivia selfcare objective index [--page N --per-page N --selfcare-content-id ID --objective-id ID]
                                                 List a selfcare content's associated objectives

data/lib/holivia/cli.rb

@@ -9,10 +9,11 @@ require_relative "commands/slide"
 require_relative "commands/env"
 require_relative "commands/item"
 require_relative "commands/objective"
+require_relative "commands/appointment"
 
 module Holivia
   class CLI
-    def self.start(args) # rubocop:disable Metrics/CyclomaticComplexity
+    def self.start(args) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
       command = args.shift
       case command
       when "login" then Commands::Auth.new.login(args)
@@ -20,6 +21,7 @@ module Holivia
       when "env" then Commands::Env.route(args)
       when "selfcare" then Commands::Selfcare.route(args)
       when "objective" then Commands::Objective.route(args)
+      when "appointment" then Commands::Appointment.route(args)
       when "version", "--version", "-v" then puts "holivia #{Holivia::VERSION}"
       when "--help", "-h", nil then puts Help::HELP_TEXT
       else warn "Unknown command: #{command}"

data/lib/holivia/commands/appointment.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Holivia
+  module Commands
+    class Appointment < Base
+      BASE_PATH = "/api/v1/backoffice/appointments"
+
+      def self.route(args)
+        subcommand = args.shift
+        case subcommand
+        when "video-diagnostics" then new.video_diagnostics(args)
+        else warn "Unknown appointment command: #{subcommand}"
+             exit 1
+        end
+      end
+
+      def video_diagnostics(args = [])
+        id = args.shift
+        abort "Usage: holivia appointment video-diagnostics <id>" unless id
+
+        output(client.get("#{BASE_PATH}/#{id}/video_diagnostics"))
+      end
+    end
+  end
+end

data/lib/holivia/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Holivia
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: holivia
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Holivia
@@ -52,6 +52,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- SKILL.md
 - example_content.xml
 - examples/compose.json
 - exe/holivia
@@ -61,6 +62,7 @@ files:
 - lib/holivia/cli.rb
 - lib/holivia/cli/help.rb
 - lib/holivia/client.rb
+- lib/holivia/commands/appointment.rb
 - lib/holivia/commands/auth.rb
 - lib/holivia/commands/base.rb
 - lib/holivia/commands/env.rb