🚧 wip-ruby – WIP.co API wrapper for Ruby

gem 'wip-ruby'

# config/initializers/wip.rb

Wip.configure do |config|
  # Required: Your WIP API key
  config.api_key = Rails.application.credentials.dig(Rails.env.to_sym, :wip, :api_key)

  # Optional: API base URL (default: "https://api.wip.co")
  config.base_url = "https://api.wip.co"

  # Optional: Request timeout in seconds (default: 10, range: 1-60)
  config.timeout = 10

  # Optional: Number of retries for failed requests (default: 2, range: 0-5)
  config.max_retries = 2

  # Optional: Logger for debugging (default: nil)
  config.logger = Rails.logger
end

require 'wip-ruby'

Wip.configure do |config|
  config.api_key = ENV['WIP_API_KEY']
end

# Create a client
client = Wip::Client.new

# Get your profile
me = client.viewer.me
puts "Hello, #{me.full_name}!"
puts "Current streak: #{me.streak} days"

# Create a todo
todo = client.todos.create(body: "Shipped a new feature! #myproject")
puts "Created: #{todo.url}"

# List your recent todos
client.viewer.todos(limit: 5).each do |todo|
  puts "- #{todo.body}"
end

# Get your profile
me = client.viewer.me
puts me.username         # => "marc"
puts me.full_name        # => "Marc Kohlbrugge"
puts me.streak           # => 365
puts me.best_streak      # => 500
puts me.todos_count      # => 1234
puts me.on_streak?       # => true
puts me.avatar_url       # => "https://..." (medium size)
puts me.avatar_url(:large)  # => "https://..." (large size)

# List your todos
todos = client.viewer.todos
todos = client.viewer.todos(limit: 10)
todos = client.viewer.todos(since: "2024-01-01")
todos = client.viewer.todos(since: Date.today - 7, before: Date.today)

# List your projects
projects = client.viewer.projects
projects = client.viewer.projects(limit: 5)

# Create a todo
todo = client.todos.create(body: "Launched my new app! #myapp")
puts todo.id
puts todo.body
puts todo.url
puts todo.created_at

# Create a todo with attachments
signed_id = client.uploads.upload("screenshot.png")
todo = client.todos.create(
  body: "Check out this screenshot!",
  attachments: [signed_id]
)

# Get a specific todo
todo = client.todos.find("todo_123")
puts todo.body
puts todo.reactions_count
puts todo.comments_count

# Check todo properties
puts "Has attachments" if todo.attachments?
puts "In projects: #{todo.projects.map(&:name).join(', ')}" if todo.projects?
puts "Has comments" if todo.comments?
puts "Has reactions" if todo.reactions?

# Check viewer interaction
puts "You reacted" if todo.reacted_by_viewer?
puts "You commented" if todo.commented_by_viewer?

# Get a user's profile
user = client.users.find("marc")
puts user.username
puts user.full_name
puts user.streak
puts user.best_streak
puts user.todos_count
puts user.time_zone
puts user.url
puts user.avatar_url(:small)
puts user.avatar_url(:medium)
puts user.avatar_url(:large)

# Check user properties
puts user.on_streak?     # Currently streaking?
puts user.protected?     # Protected account?
puts user.streaking?     # Actively streaking?

# List a user's projects
projects = client.users.projects("marc")
projects = client.users.projects("marc", limit: 10)

# List a user's todos
todos = client.users.todos("marc")
todos = client.users.todos("marc", limit: 20, since: "2024-01-01")
todos = client.users.todos("marc",
  since: Time.now - 86400 * 30,  # Last 30 days
  before: Time.now
)

# Get a project
project = client.projects.find("project_123")
puts project.name
puts project.slug
puts project.hashtag
puts project.pitch
puts project.description
puts project.website_url
puts project.url
puts project.created_at
puts project.updated_at

# Check project properties
puts project.protected?      # Protected project?
puts project.archived?       # Archived project?
puts project.logo?           # Has a logo?
puts project.team_project?   # Multiple makers?

# Get project logo
puts project.logo_url(:small)
puts project.logo_url(:medium)
puts project.logo_url(:large)

# Get project owner
owner = project.owner
puts "Owner: #{owner.full_name}"

# Get all project makers
project.makers.each do |maker|
  puts "- #{maker.full_name} (@#{maker.username})"
end

# List project todos
todos = client.projects.todos("project_123")
todos = client.projects.todos("project_123",
  limit: 25,
  since: "2024-01-01",
  before: "2024-12-31"
)

# List comments for a todo
comments = client.comments.for_todo("todo_123")
comments = client.comments.for_todo("todo_123", limit: 10)

comments.each do |comment|
  puts "#{comment.creator.username}: #{comment.body}"
  puts "  Reactions: #{comment.reactions_count}"
  puts "  Created: #{comment.created_at}"
end

# Create a comment
comment = client.comments.create(
  commentable_type: "Todo",
  commentable_id: "todo_123",
  body: "Great work on this!"
)
puts "Comment created: #{comment.id}"

# Update a comment (your own comments only)
updated = client.comments.update("comment_123", body: "Updated comment text")
puts "Updated at: #{updated.updated_at}"

# Delete a comment (your own comments only)
client.comments.delete("comment_123")

# Check if you've reacted to a comment
puts "You liked this" if comment.reacted_by_viewer?

# React to a todo (convenience method)
reaction = client.reactions.react_to_todo("todo_123")
puts "Reacted by: #{reaction.reactor.username}"

# React to a comment (convenience method)
reaction = client.reactions.react_to_comment("comment_123")

# React using the generic method
reaction = client.reactions.create(
  reactable_type: "Todo",     # "Todo" or "Comment"
  reactable_id: "todo_123"
)

# Check reaction properties
puts reaction.on_todo?       # => true
puts reaction.on_comment?    # => false
puts reaction.reactable_type # => "Todo"
puts reaction.reactable_id   # => "todo_123"
puts reaction.created_at

# Remove a reaction (your own reactions only)
client.reactions.delete("reaction_123")

# Simple upload (recommended)
signed_id = client.uploads.upload("path/to/screenshot.png")

# Create todo with the uploaded file
todo = client.todos.create(
  body: "Check out this screenshot!",
  attachments: [signed_id]
)

# Upload multiple files
signed_ids = [
  client.uploads.upload("screenshot1.png"),
  client.uploads.upload("screenshot2.png")
]
todo = client.todos.create(
  body: "Multiple screenshots attached!",
  attachments: signed_ids
)

require 'digest'

file_path = "path/to/file.png"

# Step 1: Request pre-signed upload URL
credentials = client.uploads.request_upload_url(
  filename: File.basename(file_path),
  byte_size: File.size(file_path),
  checksum: Digest::MD5.file(file_path).base64digest,
  content_type: "image/png"
)

# The credentials hash contains:
# - url: Pre-signed upload URL
# - method: HTTP method to use (usually "PUT")
# - headers: Headers to include in upload request
# - signed_id: ID to reference the upload
# - key: Storage key

# Step 2: Upload the file
success = client.uploads.upload_file(
  url: credentials["url"],
  headers: credentials["headers"],
  file_path: file_path,
  method: credentials["method"]  # Optional, defaults to PUT
)

# Step 3: Use the signed_id in your todo
if success
  todo = client.todos.create(
    body: "Uploaded!",
    attachments: [credentials["signed_id"]]
  )
end

user.full_name           # "First Last"
user.avatar_url(:size)   # Avatar URL for :small, :medium, or :large
user.on_streak?          # Currently on an active streak?
user.todos?              # Has completed any todos?

todo.attachments?         # Has attachments?
todo.projects?            # Belongs to projects?
todo.comments?            # Has comments?
todo.reactions?           # Has reactions?
todo.viewer_reactions     # Your reactions on this todo
todo.viewer_comments      # Your comments on this todo
todo.reacted_by_viewer?   # Have you reacted?
todo.commented_by_viewer? # Have you commented?

project.logo?             # Has a logo?
project.logo_url(:size)   # Logo URL for :small, :medium, or :large
project.team_project?     # Has multiple makers?

comment.reactions?        # Has reactions?
comment.viewer_reactions  # Your reactions on this comment
comment.reacted_by_viewer? # Have you reacted?

reaction.on_todo?     # Is this on a todo?
reaction.on_comment?  # Is this on a comment?

collection.each { |item| ... }  # Iterate items (Enumerable)
collection.size                 # Number of items in this page
collection.length               # Alias for size
collection.count                # Alias for size
collection.empty?               # Is collection empty?
collection.first                # First item
collection.last                 # Last item
collection.last_id              # ID of last item (for pagination)
collection.has_more             # Are there more pages?
collection.total_count          # Total items across all pages

# Get first page (default: 25 items)
todos = client.users.todos("marc")
puts "Page 1: #{todos.size} items"
puts "Total: #{todos.total_count}"
puts "Has more: #{todos.has_more}"

# Get next page
if todos.has_more
  next_page = client.users.todos("marc",
    starting_after: todos.last_id
  )
end

# Custom page size
todos = client.users.todos("marc", limit: 50)

# Iterate through all pages
def fetch_all_todos(client, username)
  all_todos = []
  cursor = nil

  loop do
    page = client.users.todos(username,
      limit: 100,
      starting_after: cursor
    )
    all_todos.concat(page.data)
    break unless page.has_more
    cursor = page.last_id
  end

  all_todos
end

# Using Time objects
todos = client.viewer.todos(
  since: Time.now - 86400 * 7,   # 7 days ago
  before: Time.now
)

# Using Date objects
todos = client.viewer.todos(
  since: Date.today - 30,
  before: Date.today
)

# Using ISO 8601 strings
todos = client.viewer.todos(
  since: "2024-01-01",
  before: "2024-12-31"
)

# Using partial dates
todos = client.viewer.todos(since: "2024")      # Year only
todos = client.viewer.todos(since: "2024-06")   # Year and month

# Using Unix timestamps
todos = client.viewer.todos(
  since: 1704067200,  # 2024-01-01 00:00:00 UTC
  before: 1735689600  # 2025-01-01 00:00:00 UTC
)

begin
  client.todos.create(body: "New todo!")
rescue Wip::Error::ConfigurationError => e
  # Invalid configuration (missing API key, etc.)
  puts "Config error: #{e.message}"

rescue Wip::Error::UnauthorizedError => e
  # Invalid API key (HTTP 401)
  puts "Auth failed: #{e.message}"

rescue Wip::Error::ForbiddenError => e
  # Access denied (HTTP 403)
  puts "Forbidden: #{e.message}"

rescue Wip::Error::NotFoundError => e
  # Resource not found (HTTP 404)
  puts "Not found: #{e.message}"

rescue Wip::Error::ValidationError => e
  # Invalid request data (HTTP 400, 422)
  puts "Validation error: #{e.message}"
  puts "Details: #{e.response_data}"

rescue Wip::Error::RateLimitError => e
  # Too many requests (HTTP 429)
  puts "Rate limited: #{e.message}"
  puts "Status code: #{e.status_code}"

rescue Wip::Error::ServerError => e
  # WIP server error (HTTP 5xx)
  puts "Server error: #{e.message}"

rescue Wip::Error::TimeoutError => e
  # Request timed out
  puts "Timeout: #{e.message}"

rescue Wip::Error::ConnectionError => e
  # Network connection failed
  puts "Connection error: #{e.message}"

rescue Wip::Error::UploadError => e
  # File upload failed
  puts "Upload error: #{e.message}"

rescue Wip::Error::NetworkError => e
  # Other network errors
  puts "Network error: #{e.message}"

rescue Wip::Error => e
  # Catch-all for any WIP error
  puts "Error: #{e.message}"
  puts "Status: #{e.status_code}" if e.status_code
end

error.message       # Human-readable error message
error.status_code   # HTTP status code (if applicable)
error.response_data # Raw response body (if applicable)

Wip.configure do |config|
  config.max_retries = 3  # 0 to disable retries, max 5
end

Wip.configure do |config|
  config.logger = Logger.new($stdout)
  # Or in Rails:
  config.logger = Rails.logger
end