talknote_rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 899d91f6767394e1d26d6f6a1ab4715be0a33c911bcfdb37f4c3fac45274d886
-  data.tar.gz: '09368484efcde3c642968574562f28b715beba1553f2335f40753b332cef2b49'
+  metadata.gz: e6d214dec33ec2622bfe1d52931690bf988e6f7d825dda2f37bd9cb219ebf28d
+  data.tar.gz: 4df093e513a0d9b56e49103a3e729d0fc6da3610993eea2ca82c6aa6da3865ab
 SHA512:
-  metadata.gz: bae3eff4b62ab61ce8e0da775eb4cfa98e6266c620e5d8186649e776c9c024769ddfa43c4d4c35a17a952f39e773872ec2c6df935b6306daeeb4f1cc5edde6cc
-  data.tar.gz: d4a89fed111da05293d8d87d1f163a4176e6fcc462a7f724c6570ecdf85df3ee8ce63e6cc494d4342b6ad70d354b4c9d7c590debf05f309bf9d1cbbae9914591
+  metadata.gz: 58038dfcafd4a41f0652a712511d1349bd3e3ecd854df2c0ba9474c5149ef96954d8fa031c18c37e08ec47a148b9b436400e1839b5408b53df0fe921daeba6f1
+  data.tar.gz: 273b08d4029be1147174e224b2f0043e4a40b0a05277046b368341738f6a1172e23c29e0e7e463b9db652a5eb20c142194de094cdef5093f3c1d542cb204c37f

data/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: bundler # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

data/.github/workflows/main.yml

@@ -0,0 +1,37 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['3.3', '3.4', 'head', 'debug']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: |
+        bundle exec rake
+    - name: CodeCov
+      uses: codecov/codecov-action@v3
+      with:
+        files: ./coverage/coverage.xml

data/Gemfile

@@ -1,7 +1,10 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in talknote_rb.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
-gem "rspec", "~> 3.0"
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.12'
+gem 'simplecov', '~> 0.21.0', require: false
+gem 'simplecov-cobertura', require: false
+gem 'csv', '~> 3.0'

data/Gemfile.lock

@@ -1,53 +1,90 @@
 PATH
   remote: .
   specs:
-    talknote_rb (0.1.0)
-      faraday
-      oauth2
+    talknote_rb (0.2.0)
+      base64
+      bigdecimal
+      csv (~> 3.0)
+      faraday (~> 2.0)
+      json
+      oauth2 (~> 2.0)
       thor
+      webrick
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.4.4)
-    faraday (1.1.0)
-      multipart-post (>= 1.2, < 3)
-      ruby2_keywords
-    jwt (2.2.2)
-    multi_json (1.15.0)
-    multi_xml (0.6.0)
-    multipart-post (2.1.1)
-    oauth2 (1.4.4)
-      faraday (>= 0.8, < 2.0)
-      jwt (>= 1.0, < 3.0)
-      multi_json (~> 1.3)
+    base64 (0.3.0)
+    bigdecimal (3.2.2)
+    csv (3.3.5)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    faraday (2.13.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    hashie (5.0.0)
+    json (2.12.2)
+    jwt (3.0.0)
+      base64
+    logger (1.7.0)
+    multi_xml (0.7.2)
+      bigdecimal (~> 3.1)
+    net-http (0.6.0)
+      uri
+    oauth2 (2.0.12)
+      faraday (>= 0.17.3, < 4.0)
+      jwt (>= 1.0, < 4.0)
+      logger (~> 1.2)
       multi_xml (~> 0.5)
-      rack (>= 1.2, < 3)
-    rack (2.2.3)
-    rake (12.3.3)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+      rack (>= 1.2, < 4)
+      snaky_hash (~> 2.0, >= 2.0.3)
+      version_gem (>= 1.1.8, < 3)
+    rack (3.1.16)
+    rake (13.3.0)
+    rexml (3.4.1)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.4)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
-    ruby2_keywords (0.0.2)
-    thor (1.0.1)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-cobertura (2.1.0)
+      rexml
+      simplecov (~> 0.19)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    snaky_hash (2.0.3)
+      hashie (>= 0.1.0, < 6)
+      version_gem (>= 1.1.8, < 3)
+    thor (1.3.2)
+    uri (1.0.3)
+    version_gem (1.1.8)
+    webrick (1.9.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  rake (~> 12.0)
-  rspec (~> 3.0)
+  csv (~> 3.0)
+  rake (~> 13.0)
+  rspec (~> 3.12)
+  simplecov (~> 0.21.0)
+  simplecov-cobertura
   talknote_rb!
 
 BUNDLED WITH
-   2.1.4
+   2.3.21

data/README.md

@@ -1,8 +1,22 @@
+[![Gem Version](https://badge.fury.io/rb/talknote_rb.svg)](https://badge.fury.io/rb/talknote_rb)
+[![CI](https://github.com/geeknees/talknote_rb/actions/workflows/main.yml/badge.svg)](https://github.com/geeknees/talknote_rb/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/geeknees/talknote_rb/branch/main/graph/badge.svg?token=7RC22M1SBP)](https://codecov.io/gh/geeknees/talknote_rb)
+[![Maintainability](https://api.codeclimate.com/v1/badges/88fc1b8704b06c013b7b/maintainability)](https://codeclimate.com/github/geeknees/talknote_rb/maintainability)
+![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/geeknees/talknote_rb)
+![GitHub](https://img.shields.io/github/license/geeknees/talknote_rb)
+
 # TalknoteRb
 
-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/talknote_rb`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby client library for the Talknote API. This gem provides a simple interface to interact with Talknote's REST API, allowing you to access direct messages, groups, and other Talknote features programmatically.
+
+## Features
 
-TODO: Delete this and the text above, and describe your gem
+- 🔐 OAuth 2.0 authentication flow
+- 💬 Direct message management
+- 👥 Group conversation access
+- 📊 Unread message tracking
+- 🖥️ Command-line interface
+- 💎 Simple Ruby API client
 
 ## Installation
 
@@ -20,35 +34,359 @@ Or install it yourself as:
 
     $ gem install talknote_rb
 
+**Note:** The CSV export examples require the `csv` gem, which is included as a dependency. If you're using Ruby 3.0+, make sure to include it in your Gemfile:
+
+```ruby
+gem 'csv', '~> 3.0'
+```
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install talknote_rb
+
+## Quick Start
+
+1. Get your client credentials from the [Talknote Developer Console](https://developer.talknote.com/doc/#intro)
+2. Run the authentication setup:
+   ```sh
+   bundle exec talknote init -i your_client_id -s your_client_secret
+   ```
+3. Start using the API:
+   ```sh
+   bundle exec talknote dm
+   ```
+
 ## Usage
 
-### Get code to use API
+### Authentication
 
-See doc.
-https://developer.talknote.com/doc/#intro
+Before using the API, you need to set up authentication. First, obtain your client credentials from the [Talknote Developer Console](https://developer.talknote.com/doc/#intro).
 
-To set it up, run the following command, then the access_token will be saved in `~/.config/talknote/token.json`.
+To initialize and authenticate, run:
 
 ```sh
-bundle exec talknote init -i client_id -s client_secret
+bundle exec talknote init -i your_client_id -s your_client_secret
 ```
 
-Then, Execute various commands.
+This command will:
+1. Open your browser to the Talknote OAuth authorization page
+2. Start a local server to handle the OAuth callback
+3. Save your access token to `~/.config/talknote/token.json`
 
+You can also specify custom host and port for the OAuth callback:
+
+```sh
+bundle exec talknote init -i your_client_id -s your_client_secret -h localhost -p 8080
+```
+
+### CLI Commands
+
+#### Authentication
+```sh
+# Initialize authentication (run this first)
+talknote init -i CLIENT_ID -s CLIENT_SECRET
+
+# Optional: specify custom callback host/port
+talknote init -i CLIENT_ID -s CLIENT_SECRET -h localhost -p 9000
+```
+
+#### Direct Messages
 ```sh
-bundle exec talknote dm
+# List all DM conversations
+talknote dm
+
+# Show messages from a specific DM conversation
+talknote dm-list DM_ID
+
+# Show unread count for a DM conversation
+talknote dm-unread DM_ID
+
+# Send a message to a DM conversation
+talknote dm-post DM_ID "Your message here"
+```
+
+#### Groups
+```sh
+# List all groups
+talknote group
+
+# Show messages from a specific group
+talknote group-list GROUP_ID
+
+# Show unread count for a group
+talknote group-unread GROUP_ID
+
+# Send a message to a group
+talknote group-post GROUP_ID "Your message here"
+```
+
+## Library Usage
+
+### Setup
+
+```ruby
+require 'talknote_rb'
+
+# Client will automatically load token from ~/.config/talknote/token.json
+client = Talknote::Client.new
+```
+
+### Direct Messages
+
+```ruby
+# Get all DM conversations
+conversations = client.dm
+
+# Get messages from a specific conversation
+messages = client.dm_list('conversation_id')
+
+# Send a message
+result = client.dm_post('conversation_id', 'Hello!')
+```
+
+### Groups
+
+```ruby
+# Get all groups
+groups = client.group
+
+# Get messages from a specific group
+messages = client.group_list('group_id')
+
+# Get unread count
+unread_count = client.group_unread('group_id')
+
+# Send a message to a group
+result = client.group_post('group_id', 'Hello group!')
+```
+
+### CSV Export Examples
+
+**⚠️ Note**: CSV export operations are high-load processes. For large datasets, they may take considerable time and could be interrupted by API rate limits or server load restrictions.
+
+```ruby
+require 'talknote_rb'
+require 'csv'
+
+client = Talknote::Client.new
+
+# Export DM conversations to CSV
+CSV.open('dm_export.csv', 'w', encoding: 'UTF-8') do |csv|
+  csv << ['conversation_id', 'conversation_name', 'message_id', 'sender_name', 'message', 'created_at']
+
+  dm_response = client.dm
+  conversations = dm_response.dig('data', 'threads') || []
+
+  conversations.each do |conversation|
+    messages_response = client.dm_list(conversation['id'])
+    messages = messages_response.dig('data', 'messages') || []
+
+    messages.each do |message|
+      csv << [
+        conversation['id'],
+        conversation['name'],
+        message['id'],
+        message['sender_name'],
+        message['message'],
+        message['created_at']
+      ]
+    end
+  end
+end
+
+# Export group conversations to CSV
+CSV.open('group_export.csv', 'w', encoding: 'UTF-8') do |csv|
+  csv << ['group_id', 'group_name', 'message_id', 'sender_name', 'message', 'created_at']
+
+  groups_response = client.group
+  groups = groups_response.dig('data', 'groups') || []
+
+  groups.each do |group|
+    messages_response = client.group_list(group['id'])
+    messages = messages_response.dig('data', 'messages') || []
+
+    messages.each do |message|
+      csv << [
+        group['id'],
+        group['name'],
+        message['id'],
+        message['sender_name'],
+        message['message'],
+        message['created_at']
+      ]
+    end
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  result = client.dm
+rescue Talknote::Error => e
+  puts "API Error: #{e.message}"
+end
+```
+
+## Configuration
+
+The authentication token is stored in `~/.config/talknote/token.json` after running the `init` command. The file contains the OAuth 2.0 access token and refresh token.
+
+## API Endpoints
+
+This gem supports the following Talknote API endpoints:
+
+### Direct Messages
+- `GET /api/v1/dm` - List DM conversations
+- `GET /api/v1/dm/list/:id` - Get messages from a conversation
+- `GET /api/v1/dm/unread/:id` - Get unread count
+- `POST /api/v1/dm/post/:id` - Send a message
+
+### Groups
+- `GET /api/v1/group` - List groups
+- `GET /api/v1/group/list/:id` - Get messages from a group
+- `GET /api/v1/group/unread/:id` - Get unread count
+- `POST /api/v1/group/post/:id` - Send a message to group
+
+## Permissions
+
+Make sure your Talknote application has the necessary scopes:
+
+### DM Permissions
+- `talknote.direct_message`
+- `talknote.direct_message.read`
+- `talknote.direct_message.write`
+- `talknote.direct_message.unread`
+- `talknote.direct_message.message.read`
+- `talknote.direct_message.message.write`
+
+### Group Permissions
+- `talknote.group`
+- `talknote.group.read`
+- `talknote.group.write`
+- `talknote.group.unread`
+- `talknote.group.message.read`
+- `talknote.group.message.write`
+
+### Additional Permissions
+- `talknote.user.read`
+- `talknote.user.write`
+- `talknote.timeline.read`
+- `talknote.timeline.write`
+- `talknote.timeline.message.read`
+- `talknote.timeline.message.write`
+- `talknote.timeline.unread`
+- `talknote.allfeed.read`
+- `talknote.allfeed.unread`
+
+## Examples
+
+The `examples/` directory contains practical usage examples:
+
+- `examples/dm_example.rb` - Basic DM operations
+- `examples/group_example.rb` - Basic group operations
+- `examples/dm_csv_export_example.rb` - Export all DM conversations to CSV
+- `examples/group_csv_export_example.rb` - Export all group conversations to CSV
+- `examples/complete_csv_export_example.rb` - Export everything to organized CSV files
+
+### Example: Export all conversations to CSV
+
+```bash
+# Export all DM conversations to CSV
+ruby examples/dm_csv_export_example.rb
+
+# Export all group conversations to CSV
+ruby examples/group_csv_export_example.rb
+
+# Export everything to organized directory
+ruby examples/complete_csv_export_example.rb
+```
+
+**⚠️ Important Notes for CSV Export:**
+- **High-load processing warning**: Export operations are resource-intensive processes that may be terminated by server-side load limits or API rate limits
+- Large numbers of conversations may take significant time to export (potentially hours for thousands of conversations)
+- The export process includes rate limiting delays (1 second between each conversation) to avoid API throttling
+- **If the process stops unexpectedly**, wait some time before re-running to avoid further rate limiting
+- Each API call is logged with progress indicators to track export status
+- Export can be interrupted with Ctrl+C and resumed later
+- For large exports, consider running the specific DM or Group exporters separately instead of the complete export
+- Monitor your system resources during large exports as they may consume significant memory
+
+The CSV export examples will create files with the following structure:
+
+**DM CSV format:**
+- `conversation_id`, `conversation_name`, `message_id`, `user_id`, `user_name`, `message`, `created_at`, `message_type`
+
+**Group CSV format:**
+- `group_id`, `group_name`, `message_id`, `user_id`, `user_name`, `message`, `created_at`, `message_type`, `unread_count`
+
+### Example: Send a daily report to a group
+
+```ruby
+require 'talknote_rb'
+
+client = Talknote::Client.new
+
+# Get all groups and find the right one
+groups = client.group
+group = groups.dig('data', 'groups')&.find { |g| g['name'].include?('Daily Reports') }
+
+if group
+  # Send daily report
+  report = "📊 Daily Report (#{Date.today})\n\n" \
+           "- Tasks completed: 15\n" \
+           "- Issues resolved: 3\n" \
+           "- New features deployed: 2"
+
+  client.group_post(group['id'], report)
+  puts "Daily report sent to #{group['name']}!"
+else
+  puts "Daily Reports group not found"
+end
+```
+
+### Example: Monitor unread messages
+
+```ruby
+require 'talknote_rb'
+
+client = Talknote::Client.new
+
+# Check unread DMs
+dm_conversations = client.dm
+dm_conversations.dig('data', 'threads')&.each do |dm|
+  unread = client.dm_unread(dm['id'])
+  unread_count = unread.dig('data', 'unread_count')
+
+  if unread_count && unread_count > 0
+    puts "📩 #{dm['title']}: #{unread_count} unread messages"
+  end
+end
+
+# Check unread group messages
+groups = client.group
+groups.dig('data', 'groups')&.each do |group|
+  unread = client.group_unread(group['id'])
+  unread_count = unread.dig('data', 'unread_count')
+
+  if unread_count && unread_count > 0
+    puts "👥 #{group['name']}: #{unread_count} unread messages"
+  end
+end
 ```
 
 ## 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.
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/geeknees/talknote_rb. 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]/talknote_rb/blob/master/CODE_OF_CONDUCT.md).
-
+Bug reports and pull requests are welcome on GitHub at https://github.com/geeknees/talknote_rb. 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/geeknees/talknote_rb/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -56,4 +394,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the TalknoteRb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/talknote_rb/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the TalknoteRb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/geeknees/talknote_rb/blob/main/CODE_OF_CONDUCT.md).