gslide 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fe444ca4bdef588c1e0aadf54db33d2024612b4d3450c4da243bd7ea3538055
-  data.tar.gz: 5416cb52420d81d5c5f8e4f99a13d2745e405a372c780314debb67c64e4c1b61
+  metadata.gz: b3f719011cb4ab8f9e07b8f03bf76609302e6ea2491d1f6dd8dad5c7534c0eed
+  data.tar.gz: eca34767fba2927ee5d01966c261a2251146d89922f942643f91b3ae56581cec
 SHA512:
-  metadata.gz: 5477601ab8d237e62853bf974c1e3961fbd60e5197822754cdfe1d903a2bc37983395c412b674b27c8405fa3883d6b48291b384c49a619c7c4334f7bab719256
-  data.tar.gz: 518e86e5a3ececa73d696c737f3d0672f21fae300f5e57b2aa53c1de8fde8a9d925e1cadbbfd3c2048d9af90d41a3cd0765cd61f445bd9a78bc39c1183aafccd
+  metadata.gz: cd49143158ee8e357dca44cfa114b5be71eee28bec81499c0d8e81ee575550b8cdf214c8a2eba2e41a41e602d7d485ce3c7032779301a897360d53be4a7cde4a
+  data.tar.gz: 0c0657e347e66e54d1408490bf587ac814fab41968ef071894e8aad84ae506e507ad3ce887b3f4be56e79a6f8373c68829e0c7990ffdb68dda85f9125d88d377

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [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

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,3 +1,4 @@
+require "json"
 require "net/http"
 
 module Gslide
@@ -5,58 +6,131 @@ 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
@@ -10,6 +11,22 @@ module Gslide
       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)
@@ -47,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gslide
-  VERSION = "0.1.3"
+  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.3
+  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