gslide 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c60628d84c354c773b26428a27bf090324f9d480e7fbaa21f61b9eff373afcfd
-  data.tar.gz: 35dfbc790360627c4829f6747e9e25532ab0342d8044c61259e77bf050e85f2c
+  metadata.gz: b3f719011cb4ab8f9e07b8f03bf76609302e6ea2491d1f6dd8dad5c7534c0eed
+  data.tar.gz: eca34767fba2927ee5d01966c261a2251146d89922f942643f91b3ae56581cec
 SHA512:
-  metadata.gz: 3998d8e6e183a9a7f1bc4164284a26fa4296c11187dcbf848f8dbe0f75ba6fdc5bb6b9e4407007d1cd7a11d6fd3f5c46b023b7fcda9000a23f3c2fdf0c88eddf
-  data.tar.gz: '086712b43b87c1a09ee7563c028af143282dc22f3fd74762c0e0dd2d99c81f8d78268affa80be92b1f3eb6e5fe98700356132d8d7f97f6d59ed9e50535333228'
+  metadata.gz: cd49143158ee8e357dca44cfa114b5be71eee28bec81499c0d8e81ee575550b8cdf214c8a2eba2e41a41e602d7d485ce3c7032779301a897360d53be4a7cde4a
+  data.tar.gz: 0c0657e347e66e54d1408490bf587ac814fab41968ef071894e8aad84ae506e507ad3ce887b3f4be56e79a6f8373c68829e0c7990ffdb68dda85f9125d88d377

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.2.0] - 2026-11-14
+
+- Add `Gslide::Presentation.generate_object_id` and `Gslide::Presentation::OBJECT_ID_PATTERN`, for IDs of new pages and page elements
+- Require `json`, so gslide works outside Rails
+- Add `ForbiddenError` (403), `NotFoundError` (404), `ServerError` (5xx) and `TimeoutError`
+- Raise `Gslide::ServerError` instead of `JSON::ParserError` when an error response is not JSON, such as an HTML 502 page
+- Include Google's message in `Gslide::QuotaExceededError`; treat Drive's 403 rate-limit errors as quota errors
+- Retry GET requests on quota errors, 5xx and timeouts (3 attempts); POST requests are not retried, except `batch_update` on quota errors as before
+- Set open (10 s) and read (60 s) timeouts
+- Add `Gslide::Models::Drive#trash` (a file already gone counts as done)
+- Add `Gslide::Models::Drive#rename`
+- Add `Gslide::Models::Drive#copy`, e.g. a template into a folder (works with the `drive.file` scope and shared drives)
+
+## [0.1.3] - 2026-08-19
+
+- Add `Gslide::Presentation::PRESENTATION_ID_PATTERN` and `Gslide::Presentation.file_id_in`, so callers can validate a presentation id without repeating the pattern
+
 ## [0.1.2] - 2025-05-09
 
 - Add `Gslide::HTTPError`, `Gslide::UnauthorizedError` and `Gslide::QuotaExceededError` #10

data/README.md

@@ -92,6 +92,18 @@ pres.batch_update({
 #=> true
 ```
 
+Copy a template into a folder, rename a file, and trash a file. Works with the `drive.file` scope for files the user picked (for example with Google Picker) or the app created.
+
+```rb
+drive = Gslide::Drive.new(auth: editor)
+deck_id = drive.copy(template_id, name: "Report", folder_id: folder_id)
+#=> "1itXwmlLbyTRa1QKhrsO16OhJPEJUK6eh2d1nqsQfuqY"
+drive.rename(deck_id, name: "Monthly Report")
+#=> true
+drive.trash(deck_id)
+#=> true (also when the file is already gone)
+```
+
 ## Development
 
 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.

data/lib/gslide/concerns/requests.rb

@@ -1,60 +1,136 @@
+require "json"
 require "net/http"
 
 module Gslide
+
+  # @private
   module Concerns
     module Requests
+      OPEN_TIMEOUT = 10
+      READ_TIMEOUT = 60
+
+      # Attempts for a GET request, including the first one.
+      # GET is safe to repeat, so it retries on quota errors, 5xx and timeouts.
+      GET_ATTEMPTS = 3
+
       def get_request(uri, auth_token: "")
-        req = Net::HTTP::Get.new(uri.to_s)
-        req['Authorization'] = "Bearer #{auth_token}"
+        attempts = 0
+        begin
+          attempts += 1
+          req = Net::HTTP::Get.new(uri.to_s)
+          perform_request(uri, req, auth_token)
+        rescue Gslide::QuotaExceededError, Gslide::ServerError, Gslide::TimeoutError
+          raise unless attempts < GET_ATTEMPTS
 
-        res = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
-          http.request(req)
-        end
-        response_body = JSON(res.body)
-
-        case res
-        when Net::HTTPSuccess
-          response_body
-        when Net::HTTPUnauthorized
-          msg = response_body["error"] ? response_body["error"]["message"] : "Unauthorized"
-          raise Gslide::UnauthorizedError, msg
-        else
-          msg = response_body["error"] ? response_body["error"]["message"] : "HTTPError"
-          raise Gslide::HTTPError, msg
+          sleep retry_delay(attempts)
+          retry
         end
       end
 
+      # POST is not retried here: a request that failed on the server may
+      # still have been applied. Callers retry where it is safe, as
+      # Presentation#batch_update does for quota errors.
       def post_request(uri, auth_token: "", body: {})
         req = Net::HTTP::Post.new(uri.to_s)
         req.initialize_http_header 'Content-Type' => 'application/json'
-        req['Authorization'] = "Bearer #{auth_token}"
+        req.body = body
 
+        perform_request(uri, req, auth_token)
+      end
+
+      # PATCH is not retried either, for the same reason as POST.
+      def patch_request(uri, auth_token: "", body: {})
+        req = Net::HTTP::Patch.new(uri.to_s)
+        req.initialize_http_header 'Content-Type' => 'application/json'
         req.body = body
 
-        res = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
+        perform_request(uri, req, auth_token)
+      end
+
+      private
+
+      # Seconds to wait after failed attempt number +attempts+: 20, 50, 100...
+      def retry_delay(attempts)
+        10 + attempts * attempts * 10
+      end
+
+      def perform_request(uri, req, auth_token)
+        req['Authorization'] = "Bearer #{auth_token}"
+
+        res = Net::HTTP.start(uri.host, uri.port,
+                              use_ssl: uri.scheme == 'https',
+                              open_timeout: OPEN_TIMEOUT,
+                              read_timeout: READ_TIMEOUT) do |http|
           http.request(req)
         end
 
-        response_body = JSON(res.body)
+        handle_response(res.code.to_i, res.body)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise Gslide::TimeoutError, "#{e.class} from #{uri.host}"
+      end
+
+      # @param [Integer] status the HTTP status code.
+      # @param [String, nil] body the response body.
+      # @return [Hash] the parsed body of a successful response.
+      def handle_response(status, body)
+        response_body = parse_body(body)
+
+        if (200..299).cover?(status)
+          return response_body if response_body
+
+          raise Gslide::HTTPError, "Invalid JSON response"
+        end
+
+        msg = error_message(response_body)
+
+        case status
+        when 401
+          raise Gslide::UnauthorizedError, msg || "Unauthorized"
+        when 403
+          if rate_limited?(response_body)
+            raise Gslide::QuotaExceededError, msg || "RateLimitExceeded"
+          end
 
-        case res
-        when Net::HTTPSuccess
-          response_body
-        when Net::HTTPUnauthorized
-          msg = response_body["error"] ? response_body["error"]["message"] : "Unauthorized"
-          raise Gslide::UnauthorizedError, msg
-        when Net::HTTPTooManyRequests
+          raise Gslide::ForbiddenError, msg || "Forbidden"
+        when 404
+          raise Gslide::NotFoundError, msg || "NotFound"
+        when 429
           # "Quota exceeded for quota metric 'Write requests' and limit 'Write requests per minute per user' of service 'slides.googleapis.com' for consumer 'project_number:012345678901'."
-          if response_body["error"] && response_body["error"]["message"] =~ /Quota exceeded/
+          if msg =~ /Quota exceeded/
             raise Gslide::QuotaExceededError, msg
           else
             raise Gslide::HTTPError, msg || "TooManyRequests"
           end
+        when 500..599
+          raise Gslide::ServerError, msg || "ServerError"
         else
-          msg = response_body["error"] ? response_body["error"]["message"] : "HTTPError"
-          raise Gslide::HTTPError, msg
+          raise Gslide::HTTPError, msg || "HTTPError"
         end
       end
+
+      # @return [Hash, nil] the parsed body, {} for an empty body,
+      #   or nil when the body is not a JSON object (e.g. an HTML error page).
+      def parse_body(body)
+        return {} if body.nil? || body.strip.empty?
+
+        parsed = JSON(body)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def error_message(response_body)
+        error = response_body && response_body["error"]
+        error.is_a?(Hash) ? error["message"] : nil
+      end
+
+      # Drive reports rate limits as 403 with one of these reasons.
+      def rate_limited?(response_body)
+        error = response_body && response_body["error"]
+        return false unless error.is_a?(Hash) && error["errors"].is_a?(Array)
+
+        error["errors"].any? { |e| %w[rateLimitExceeded userRateLimitExceeded].include?(e["reason"]) }
+      end
     end
   end
 end

data/lib/gslide/models/drive.rb

@@ -0,0 +1,68 @@
+require "gslide/concerns/requests"
+
+module Gslide
+  module Models
+    # Drive calls for decks: copy a template (into a folder), rename a file, and trash a file.
+    # Works with the narrow `drive.file` scope for files the user picked or the app created, and
+    # with shared drives.
+    #
+    #   drive = Gslide::Models::Drive.new(auth: editor)
+    #   deck_id = drive.copy(template_id, name: "Monthly Report (draft)", folder_id: folder_id)
+    #   drive.rename(deck_id, name: "Monthly Report")
+    #   drive.trash(deck_id)
+    class Drive
+      include Concerns::Requests
+
+      FILE_ID_PATTERN = /\A[a-zA-Z0-9\-_]+\z/
+
+      def initialize(auth: nil)
+        @auth = auth
+      end
+
+      # @param [String] file_id the file to copy, e.g. a template presentation.
+      # @param [String] name the copy's name.
+      # @param [String, nil] folder_id the folder to put the copy in; nil for the original's folder.
+      # @return [String] the copy's file id.
+      # @see https://developers.google.com/workspace/drive/api/reference/rest/v3/files/copy
+      def copy(file_id, name:, folder_id: nil)
+        body = { name: name }
+        body[:parents] = [checked(folder_id)] if folder_id
+        uri = URI(GOOGLE_DRIVE + "/#{checked(file_id)}/copy?supportsAllDrives=true")
+
+        post_request(uri, auth_token: @auth.token, body: body.to_json).fetch("id")
+      end
+
+      # @param [String] file_id the file to rename, e.g. a finished deck.
+      # @param [String] name its new name.
+      # @return [true]
+      # @see https://developers.google.com/workspace/drive/api/reference/rest/v3/files/update
+      def rename(file_id, name:)
+        uri = URI(GOOGLE_DRIVE + "/#{checked(file_id)}?supportsAllDrives=true")
+        patch_request(uri, auth_token: @auth.token, body: { name: name }.to_json)
+        true
+      end
+
+      # Moves the file to the trash (it can be restored from there for 30 days).
+      # @param [String] file_id the file to trash, e.g. a deck left by a failed run.
+      # @return [true] also when the file is already gone.
+      # @see https://developers.google.com/workspace/drive/api/reference/rest/v3/files/update
+      def trash(file_id)
+        uri = URI(GOOGLE_DRIVE + "/#{checked(file_id)}?supportsAllDrives=true")
+        patch_request(uri, auth_token: @auth.token, body: { trashed: true }.to_json)
+        true
+      rescue Gslide::NotFoundError
+        true
+      end
+
+      private
+
+      def checked(file_id)
+        unless file_id.to_s.match?(FILE_ID_PATTERN)
+          raise ArgumentError, "invalid Drive file id: #{file_id.inspect}"
+        end
+
+        file_id
+      end
+    end
+  end
+end

data/lib/gslide/models/models.rb

@@ -1,11 +1,13 @@
 require "gslide/models/editor"
 require "gslide/models/presentation"
 require "gslide/models/spreadsheet"
+require "gslide/models/drive"
 
 module Gslide
   module Models
     GOOGLE_SLIDES = "https://slides.googleapis.com/v1/presentations"
     GOOGLE_SHEETS = "https://sheets.googleapis.com/v4/spreadsheets"
+    GOOGLE_DRIVE = "https://www.googleapis.com/drive/v3/files"
   end
 
   include Models

data/lib/gslide/models/presentation.rb

@@ -1,3 +1,4 @@
+require "securerandom"
 require "gslide/concerns/requests"
 
 module Gslide
@@ -7,10 +8,33 @@ module Gslide
 
       attr_reader :id
 
-      PRESENTATION_PATTERN = %r[/presentation/d/([a-zA-Z0-9\-_]+)?]
+      PRESENTATION_ID_PATTERN = /[a-zA-Z0-9\-_]+/
+      PRESENTATION_PATTERN = %r[/presentation/d/(#{PRESENTATION_ID_PATTERN})?]
+
+      # An object ID (for a page, shape or table) starts with a word character,
+      # followed by word characters, dashes or colons; 5 to 50 characters long.
+      # @see https://developers.google.com/slides/api/reference/rest/v1/presentations.pages#Page.FIELDS.object_id
+      OBJECT_ID_PATTERN = /[a-zA-Z0-9_][a-zA-Z0-9_\-:]*/
+      OBJECT_ID_LENGTHS = 5..50
+
+      # @param [Integer] length from 5 to 50.
+      # @return [String] a random object ID for a new page element, e.g. "aZ3kq09XbP1t".
+      def self.generate_object_id(length = 12)
+        unless OBJECT_ID_LENGTHS.cover?(length)
+          raise ArgumentError, "object ID length must be within #{OBJECT_ID_LENGTHS}, not #{length}"
+        end
+
+        SecureRandom.alphanumeric(length)
+      end
+
+      # @param [String] id_or_url a presentation id, or a sharing url holding one.
+      # @return [String] the presentation id, or the argument when it is not a url.
+      def self.file_id_in(id_or_url)
+        (url_id = id_or_url.match(PRESENTATION_PATTERN)) ? url_id[1] : id_or_url
+      end
 
       def initialize(id_or_url, auth: nil)
-        @id = (url_id = id_or_url.match(PRESENTATION_PATTERN)) ? url_id[1] : id_or_url
+        @id = self.class.file_id_in(id_or_url)
         @auth = auth
       end
 
@@ -40,7 +64,7 @@ module Gslide
         response_body["presentationId"] == @id
       rescue Gslide::QuotaExceededError
         if (retries += 1) < 3
-          sleep 10 + retries * retries * 10
+          sleep retry_delay(retries)
 
           retry
         end

data/lib/gslide/models/spreadsheet.rb

@@ -40,6 +40,23 @@ module Gslide
         parsed_body = get
         parsed_body[:sheets].collect { |h| Sheet.new(h) }
       end
+
+      # @param [Hash] options the request body.
+      # @see https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append
+      def values_append(notation, options = {})
+        uri = url_escape_uri(GOOGLE_SHEETS + "/#{@id}/values/'#{notation}':append?valueInputOption=USER_ENTERED")
+        request_body = options.convert_keys { |k| k.to_s.lower_camel_case }.to_json
+
+        response_body = post_request(uri, auth_token: @auth.token, body: request_body)
+        response_body
+      end
+
+      private
+
+      def url_escape_uri(uri_string)
+        parser = URI::Parser.new
+        URI parser.escape(uri_string)
+      end
     end
 
     class SpreadsheetDraft
@@ -61,10 +78,11 @@ module Gslide
     end
 
     class Sheet
-      attr_reader :id, :charts
+      attr_reader :id, :title, :charts
 
       def initialize(options = {})
         @id = options[:properties][:sheet_id]
+        @title = options[:properties][:title]
         @charts = options[:charts].collect { |h| Chart.new(h) } if options[:charts]
       end
     end

data/lib/gslide/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gslide
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/gslide.rb

@@ -9,5 +9,11 @@ module Gslide
   class Error < StandardError; end
   class HTTPError < Error; end
   class UnauthorizedError < HTTPError; end
+  class ForbiddenError < HTTPError; end
+  class NotFoundError < HTTPError; end
   class QuotaExceededError < HTTPError; end
+  class ServerError < HTTPError; end
+
+  # Raised when Google does not respond in time.
+  class TimeoutError < Error; end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gslide
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Kang-Kyu Lee
@@ -23,6 +23,7 @@ files:
 - Rakefile
 - lib/gslide.rb
 - lib/gslide/concerns/requests.rb
+- lib/gslide/models/drive.rb
 - lib/gslide/models/editor.rb
 - lib/gslide/models/models.rb
 - lib/gslide/models/presentation.rb
@@ -52,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Google Slides API client.
 test_files: []