fizzy-sdk 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 384e78109de4f526da564a40adfa1d103d8d903d7c122c7893cc9c9474b75bbb
-  data.tar.gz: 561d99800e4e9f754b7d79cb18933ad1c4ac7ce3aa1c416513ac442792c4e89d
+  metadata.gz: 5cb258ecc0bb6152a3736dd03883662cf809277bc85444ed698c386ae641360a
+  data.tar.gz: 3da686f5810a68724d669fb3c4f07cac37799be99c0e1d5cc07ed235330b3679
 SHA512:
-  metadata.gz: d40802705e1cfee6c65b8806e775a13e2d7efd2cb2d75b4e84317a09b9918c3b74e024caef109971a0e6701157cac429d0469ce57a98db9cd0d1f1e3d6defc5f
-  data.tar.gz: 16d7691b3456c8068cad21fbec5cc372503b88f338a32e33e4ca43d22314b41fbf4cc30a4ef44388e3cdc60cdc2520f702fa58168bc347b47ea27debeec31600
+  metadata.gz: fd2608ea08ec97413c39d9f22ed1fca328fe917b4f3cb7fdde4a1da1d0b47725eb75cd2a2f8786b8df3a1bc929cf95c1fd20bf658e340b90372c34e5fe530f61
+  data.tar.gz: 3e32b0a281961f7c7c779b0bb0a70fcff3550aa04f732e4779ed33ce15826134034d3d56deaff1a8ad7820f6b0813177456c8a6e2ae941f8c993209a8917e13f

data/lib/fizzy/config.rb

@@ -48,7 +48,7 @@ module Fizzy
     #
     # @param base_url [String] API base URL
     # @param timeout [Integer] request timeout in seconds
-    # @param max_retries [Integer] maximum retry attempts
+    # @param max_retries [Integer] total attempts per retryable request, floored at one
     # @param base_delay [Float] initial backoff delay
     # @param max_jitter [Float] maximum jitter
     # @param max_pages [Integer] maximum pages to fetch

data/lib/fizzy/generated/metadata.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://fizzy.do/schemas/sdk-metadata.json",
   "version": "1.0.0",
-  "generated": "2026-06-01T02:39:56Z",
+  "generated": "2026-10-17T23:45:49Z",
   "operations": {
     "ListAccessTokens": {
       "retry": {
@@ -154,17 +154,10 @@
     },
     "ResetJoinCode": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "GetAccountSettings": {
@@ -834,17 +827,10 @@
     },
     "PostponeCard": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "PinCard": {
@@ -864,17 +850,10 @@
     },
     "UnpinCard": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "PublishCard": {
@@ -1030,32 +1009,18 @@
     },
     "TriageCard": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "UnTriageCard": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "WatchCard": {
@@ -1090,32 +1055,18 @@
     },
     "MoveColumnLeft": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "MoveColumnRight": {
       "retry": {
-        "maxAttempts": 3,
-        "baseDelayMs": 1000,
-        "backoff": "exponential",
-        "retryOn": [
-          429,
-          500,
-          503
-        ]
-      },
-      "idempotent": {
-        "natural": true
+        "maxAttempts": 1,
+        "baseDelayMs": null,
+        "backoff": null,
+        "retryOn": null
       }
     },
     "RegisterDevice": {

data/lib/fizzy/generated/services/boards_service.rb

@@ -20,7 +20,7 @@ module Fizzy
       # @param account_id [String] account id ID
       # @param name [String] name
       # @param all_access [Boolean, nil] all access
-      # @param auto_postpone_period_in_days [Integer, nil] auto postpone period in days
+      # @param auto_postpone_period_in_days [Integer, nil] Days of inactivity before a card is auto-postponed. One of 3, 7, 11, 30, 90 or 365 (Entropy::AUTO_POSTPONE_PERIODS_IN_DAYS); any other value is rejected with 422.
       # @param public_description [String, nil] public description
       # @return [Hash] response data
       def create(account_id:, name:, all_access: nil, auto_postpone_period_in_days: nil, public_description: nil)
@@ -39,14 +39,14 @@ module Fizzy
         end
       end
 
-      # update operation
+      # Updates a board. Send at least one of name, all_access, auto_postpone_period_in_days or public_description: the controller expects a `board` object, so a body without any of them (including one carrying only user_ids) is a 400.
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
       # @param name [String, nil] name
       # @param all_access [Boolean, nil] all access
-      # @param auto_postpone_period_in_days [Integer, nil] auto postpone period in days
+      # @param auto_postpone_period_in_days [Integer, nil] Days of inactivity before a card is auto-postponed. One of 3, 7, 11, 30, 90 or 365 (Entropy::AUTO_POSTPONE_PERIODS_IN_DAYS); any other value is rejected with 422.
       # @param public_description [String, nil] public description
-      # @param user_ids [Array, nil] user ids
+      # @param user_ids [Array, nil] Replaces the board's membership: users listed are granted access and every current member not listed loses it. Omit it to leave access unchanged. It can't be sent alone (see the operation).
       # @return [Hash] response data
       def update(account_id:, board_id:, name: nil, all_access: nil, auto_postpone_period_in_days: nil, public_description: nil, user_ids: nil)
         with_operation(service: "boards", operation: "UpdateBoard", is_mutation: true, resource_id: board_id) do

data/lib/fizzy/generated/services/cards_service.rb

@@ -69,11 +69,11 @@ module Fizzy
       # @param closer_ids [Array, nil] closer ids
       # @param card_ids [Array, nil] card ids
       # @param column_ids [Array, nil] column ids
-      # @param indexed_by [String, nil] indexed by
-      # @param sorted_by [String, nil] sorted by
-      # @param assignment_status [String, nil] assignment status
-      # @param creation [String, nil] creation
-      # @param closure [String, nil] closure
+      # @param indexed_by [String, nil] Which cards to list: "all" (default, open cards), "maybe" (awaiting triage), "closed", "not_now", "stalled", "postponing_soon" or "golden". Any other value lists the same cards as "all".
+      # @param sorted_by [String, nil] "latest" (default, most recently active first), "newest" or "oldest" (by creation). Any other value sorts as "latest".
+      # @param assignment_status [String, nil] "unassigned" lists only cards with no assignee; any other value is ignored.
+      # @param creation [String, nil] Created within: "today", "yesterday", "thisweek", "lastweek", "thismonth", "lastmonth", "thisyear" or "lastyear" (TimeWindowParser); any other value is ignored.
+      # @param closure [String, nil] Closed within: "today", "yesterday", "thisweek", "lastweek", "thismonth", "lastmonth", "thisyear" or "lastyear" (TimeWindowParser); any other value is ignored.
       # @param terms [Array, nil] terms
       # @return [Enumerator<Hash>] paginated results
       def list(account_id:, board_ids: nil, tag_ids: nil, assignee_ids: nil, creator_ids: nil, closer_ids: nil, card_ids: nil, column_ids: nil, indexed_by: nil, sorted_by: nil, assignment_status: nil, creation: nil, closure: nil, terms: nil)
@@ -86,18 +86,15 @@ module Fizzy
       # create operation
       # @param account_id [String] account id ID
       # @param title [String] title
-      # @param board_id [String, nil] board id
-      # @param column_id [String, nil] column id
+      # @param board_id [String] The board to create the card on. Required: CardsController finds it unconditionally.
       # @param description [String, nil] description
-      # @param assignee_ids [Array, nil] assignee ids
-      # @param tag_names [Array, nil] tag names
-      # @param image [String, nil] image
+      # @param image [String, nil] The signed blob id of an image uploaded with CreateDirectUpload. A caller that can't make the upload has no value to send here.
       # @param created_at [String, nil] created at
       # @param last_active_at [String, nil] last active at
       # @return [Hash] response data
-      def create(account_id:, title:, board_id: nil, column_id: nil, description: nil, assignee_ids: nil, tag_names: nil, image: nil, created_at: nil, last_active_at: nil)
+      def create(account_id:, title:, board_id:, description: nil, image: nil, created_at: nil, last_active_at: nil)
         with_operation(service: "cards", operation: "CreateCard", is_mutation: true, resource_id: account_id) do
-          http_post("/#{account_id}/cards.json", body: compact_params(title: title, board_id: board_id, column_id: column_id, description: description, assignee_ids: assignee_ids, tag_names: tag_names, image: image, created_at: created_at, last_active_at: last_active_at)).json
+          http_post("/#{account_id}/cards.json", body: compact_params(title: title, board_id: board_id, description: description, image: image, created_at: created_at, last_active_at: last_active_at)).json
         end
       end
 
@@ -111,18 +108,17 @@ module Fizzy
         end
       end
 
-      # update operation
+      # Updates a card. Send at least one of title, description, image or created_at: the controller expects a `card` object, so an empty body is a 400. Moving a card between columns is TriageCard, and between boards MoveCard.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @param title [String, nil] title
       # @param description [String, nil] description
-      # @param column_id [String, nil] column id
-      # @param image [String, nil] image
+      # @param image [String, nil] The signed blob id of an image uploaded with CreateDirectUpload. A caller that can't make the upload has no value to send here.
       # @param created_at [String, nil] created at
       # @return [Hash] response data
-      def update(account_id:, card_number:, title: nil, description: nil, column_id: nil, image: nil, created_at: nil)
+      def update(account_id:, card_number:, title: nil, description: nil, image: nil, created_at: nil)
         with_operation(service: "cards", operation: "UpdateCard", is_mutation: true, resource_id: card_number) do
-          http_patch("/#{account_id}/cards/#{card_number}", body: compact_params(title: title, description: description, column_id: column_id, image: image, created_at: created_at)).json
+          http_patch("/#{account_id}/cards/#{card_number}", body: compact_params(title: title, description: description, image: image, created_at: created_at)).json
         end
       end
 
@@ -137,7 +133,7 @@ module Fizzy
         end
       end
 
-      # assign operation
+      # Assigns the user to the card, or unassigns them if they are already assigned. This is a toggle: calling it again undoes it, and both outcomes return 204, so a retry or a repeat reverses the first call. Check the card first when the outcome matters.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @param assignee_id [String] assignee id
@@ -152,12 +148,11 @@ module Fizzy
       # move operation
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
-      # @param board_id [String] board id
-      # @param column_id [String, nil] column id
+      # @param board_id [String] The destination board. Cards::BoardsController reads no column.
       # @return [Hash] response data
-      def move(account_id:, card_number:, board_id:, column_id: nil)
+      def move(account_id:, card_number:, board_id:)
         with_operation(service: "cards", operation: "MoveCard", is_mutation: true, resource_id: card_number) do
-          http_patch("/#{account_id}/cards/#{card_number}/board.json", body: compact_params(board_id: board_id, column_id: column_id)).json
+          http_patch("/#{account_id}/cards/#{card_number}/board.json", body: compact_params(board_id: board_id)).json
         end
       end
 
@@ -216,13 +211,13 @@ module Fizzy
         end
       end
 
-      # postpone operation
+      # Moves the card to Not Now. Each call records an event, which notifies webhooks and adds a system comment to the card, even when the card's state doesn't change, so it is not safe to retry.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @return [void]
       def postpone(account_id:, card_number:)
         with_operation(service: "cards", operation: "PostponeCard", is_mutation: true, resource_id: card_number) do
-          http_post("/#{account_id}/cards/#{card_number}/not_now.json", retryable: true)
+          http_post("/#{account_id}/cards/#{card_number}/not_now.json")
           nil
         end
       end
@@ -238,13 +233,13 @@ module Fizzy
         end
       end
 
-      # unpin operation
+      # Unpins the card for the caller. Unpinning a card the caller hasn't pinned currently fails with a 500 (Card::Pinnable#unpin_by destroys a pin it didn't find), so a retry after a success fails: not idempotent.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @return [void]
       def unpin(account_id:, card_number:)
         with_operation(service: "cards", operation: "UnpinCard", is_mutation: true, resource_id: card_number) do
-          http_delete("/#{account_id}/cards/#{card_number}/pin.json")
+          http_delete("/#{account_id}/cards/#{card_number}/pin.json", retryable: false)
           nil
         end
       end
@@ -260,7 +255,7 @@ module Fizzy
         end
       end
 
-      # self_assign operation
+      # Assigns the caller to the card, or unassigns them if they are already assigned. This is a toggle: calling it again undoes it, and both outcomes return 204, so a retry or a repeat reverses the first call. Check the card first when the outcome matters.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @return [void]
@@ -271,10 +266,10 @@ module Fizzy
         end
       end
 
-      # tag operation
+      # Tags the card, or untags it if it already has the tag. The tag is created when the account has none with that title. This is a toggle: calling it again undoes it, and both outcomes return 204, so a retry or a repeat reverses the first call. Check the card first when the outcome matters.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
-      # @param tag_title [String] tag title
+      # @param tag_title [String] The tag's title; surrounding whitespace and a leading "#" are stripped.
       # @return [void]
       def tag(account_id:, card_number:, tag_title:)
         with_operation(service: "cards", operation: "TagCard", is_mutation: true, resource_id: card_number) do
@@ -283,25 +278,25 @@ module Fizzy
         end
       end
 
-      # triage operation
+      # Triages the card into a column of its board. Each call records an event, which notifies webhooks and adds a system comment to the card, even when the card's state doesn't change, so it is not safe to retry.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
-      # @param column_id [String, nil] column id
+      # @param column_id [String] A column on the card's board. Required: the controller finds it unconditionally.
       # @return [void]
-      def triage(account_id:, card_number:, column_id: nil)
+      def triage(account_id:, card_number:, column_id:)
         with_operation(service: "cards", operation: "TriageCard", is_mutation: true, resource_id: card_number) do
-          http_post("/#{account_id}/cards/#{card_number}/triage.json", body: compact_params(column_id: column_id), retryable: true)
+          http_post("/#{account_id}/cards/#{card_number}/triage.json", body: compact_params(column_id: column_id))
           nil
         end
       end
 
-      # untriage operation
+      # Sends the card back to triage (Maybe?). Each call records an event, which notifies webhooks and adds a system comment to the card, even when the card's state doesn't change, so it is not safe to retry.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @return [void]
       def untriage(account_id:, card_number:)
         with_operation(service: "cards", operation: "UnTriageCard", is_mutation: true, resource_id: card_number) do
-          http_delete("/#{account_id}/cards/#{card_number}/triage.json")
+          http_delete("/#{account_id}/cards/#{card_number}/triage.json", retryable: false)
           nil
         end
       end

data/lib/fizzy/generated/services/columns_service.rb

@@ -21,7 +21,7 @@ module Fizzy
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
       # @param name [String] name
-      # @param color [String, nil] color
+      # @param color [String, nil] The column color, as its CSS value: "var(--color-card-default)" (Blue), "var(--color-card-1)" (Gray), "var(--color-card-2)" (Tan), "var(--color-card-3)" (Yellow), "var(--color-card-4)" (Lime), "var(--color-card-5)" (Aqua), "var(--color-card-6)" (Violet), "var(--color-card-7)" (Purple) or "var(--color-card-8)" (Pink) (Color::COLORS). Any other value is stored but reads back as Blue.
       # @return [Hash] response data
       def create(account_id:, board_id:, name:, color: nil)
         with_operation(service: "columns", operation: "CreateColumn", is_mutation: true, resource_id: board_id) do
@@ -40,12 +40,12 @@ module Fizzy
         end
       end
 
-      # update operation
+      # Updates a column. Send at least one of name or color: the controller expects a `column` object, so an empty body is a 400.
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
       # @param column_id [String] column id ID
       # @param name [String, nil] name
-      # @param color [String, nil] color
+      # @param color [String, nil] The column color, as its CSS value: "var(--color-card-default)" (Blue), "var(--color-card-1)" (Gray), "var(--color-card-2)" (Tan), "var(--color-card-3)" (Yellow), "var(--color-card-4)" (Lime), "var(--color-card-5)" (Aqua), "var(--color-card-6)" (Violet), "var(--color-card-7)" (Purple) or "var(--color-card-8)" (Pink) (Color::COLORS). Any other value is stored but reads back as Blue.
       # @return [Hash] response data
       def update(account_id:, board_id:, column_id:, name: nil, color: nil)
         with_operation(service: "columns", operation: "UpdateColumn", is_mutation: true, resource_id: column_id) do

data/lib/fizzy/generated/services/identity_service.rb

@@ -15,9 +15,9 @@ module Fizzy
         end
       end
 
-      # update_timezone operation
+      # Sets the caller's time zone. The name isn't validated: one that ActiveSupport::TimeZone doesn't recognize is stored, succeeds with 204, and reads back as UTC.
       # @param account_id [String] account id ID
-      # @param timezone_name [String] timezone name
+      # @param timezone_name [String] An IANA or Rails time zone name, such as "America/Chicago" or "Central Time (US & Canada)".
       # @return [void]
       def update_timezone(account_id:, timezone_name:)
         with_operation(service: "identity", operation: "UpdateMyTimezone", is_mutation: true, resource_id: account_id) do

data/lib/fizzy/generated/services/miscellaneous_service.rb

@@ -37,9 +37,9 @@ module Fizzy
 
       # update_account_entropy operation
       # @param account_id [String] account id ID
-      # @param auto_postpone_period_in_days [Integer, nil] auto postpone period in days
+      # @param auto_postpone_period_in_days [Integer] Days of inactivity before a card is auto-postponed. One of 3, 7, 11, 30, 90 or 365 (Entropy::AUTO_POSTPONE_PERIODS_IN_DAYS); any other value is rejected with 422. Required: an empty body is a 400.
       # @return [Hash] response data
-      def update_account_entropy(account_id:, auto_postpone_period_in_days: nil)
+      def update_account_entropy(account_id:, auto_postpone_period_in_days:)
         with_operation(service: "miscellaneous", operation: "UpdateAccountEntropy", is_mutation: true, resource_id: account_id) do
           http_put("/#{account_id}/account/entropy.json", body: compact_params(auto_postpone_period_in_days: auto_postpone_period_in_days)).json
         end
@@ -75,21 +75,21 @@ module Fizzy
 
       # update_join_code operation
       # @param account_id [String] account id ID
-      # @param usage_limit [Integer, nil] usage limit
+      # @param usage_limit [Integer] How many times the join code can be redeemed. Fizzy accepts up to 10,000,000,000, but this 32-bit field holds at most 2,147,483,647. Required: an empty body is a 400.
       # @return [void]
-      def update_join_code(account_id:, usage_limit: nil)
+      def update_join_code(account_id:, usage_limit:)
         with_operation(service: "miscellaneous", operation: "UpdateJoinCode", is_mutation: true, resource_id: account_id) do
           http_patch("/#{account_id}/account/join_code.json", body: compact_params(usage_limit: usage_limit))
           nil
         end
       end
 
-      # reset_join_code operation
+      # Replaces the join code with a newly generated one and resets its usage count. Each call mints a different code and invalidates the previous one, so a retry invalidates the code the first call issued: not idempotent.
       # @param account_id [String] account id ID
       # @return [void]
       def reset_join_code(account_id:)
         with_operation(service: "miscellaneous", operation: "ResetJoinCode", is_mutation: true, resource_id: account_id) do
-          http_delete("/#{account_id}/account/join_code.json")
+          http_delete("/#{account_id}/account/join_code.json", retryable: false)
           nil
         end
       end
@@ -105,9 +105,9 @@ module Fizzy
 
       # update_account_settings operation
       # @param account_id [String] account id ID
-      # @param name [String, nil] name
+      # @param name [String] The account name. Required: the controller expects an `account` object, so an empty body is a 400.
       # @return [void]
-      def update_account_settings(account_id:, name: nil)
+      def update_account_settings(account_id:, name:)
         with_operation(service: "miscellaneous", operation: "UpdateAccountSettings", is_mutation: true, resource_id: account_id) do
           http_patch("/#{account_id}/account/settings.json", body: compact_params(name: name))
           nil
@@ -117,9 +117,9 @@ module Fizzy
       # update_board_entropy operation
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
-      # @param auto_postpone_period_in_days [Integer, nil] auto postpone period in days
+      # @param auto_postpone_period_in_days [Integer] Days of inactivity before a card is auto-postponed. One of 3, 7, 11, 30, 90 or 365 (Entropy::AUTO_POSTPONE_PERIODS_IN_DAYS); any other value is rejected with 422. Required: an empty body is a 400.
       # @return [Hash] response data
-      def update_board_entropy(account_id:, board_id:, auto_postpone_period_in_days: nil)
+      def update_board_entropy(account_id:, board_id:, auto_postpone_period_in_days:)
         with_operation(service: "miscellaneous", operation: "UpdateBoardEntropy", is_mutation: true, resource_id: board_id) do
           http_put("/#{account_id}/boards/#{board_id}/entropy.json", body: compact_params(auto_postpone_period_in_days: auto_postpone_period_in_days)).json
         end
@@ -128,16 +128,16 @@ module Fizzy
       # update_board_involvement operation
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
-      # @param involvement [String, nil] involvement
+      # @param involvement [String] The caller's involvement with the board: "access_only" or "watching" (Access#involvement). Required: the controller assigns it unconditionally.
       # @return [void]
-      def update_board_involvement(account_id:, board_id:, involvement: nil)
+      def update_board_involvement(account_id:, board_id:, involvement:)
         with_operation(service: "miscellaneous", operation: "UpdateBoardInvolvement", is_mutation: true, resource_id: board_id) do
           http_patch("/#{account_id}/boards/#{board_id}/involvement.json", body: compact_params(involvement: involvement))
           nil
         end
       end
 
-      # mark_card_read operation
+      # Marks the caller's notification for the card read. When the caller has no notification for the card, the call succeeds without changing anything.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @return [void]
@@ -148,7 +148,7 @@ module Fizzy
         end
       end
 
-      # mark_card_unread operation
+      # Marks the caller's notification for the card unread. When the caller has no notification for the card, the call succeeds without changing anything.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @return [void]
@@ -159,24 +159,24 @@ module Fizzy
         end
       end
 
-      # move_column_left operation
+      # Swaps the column with its left neighbor. Each call moves it again, so it is not idempotent; at the leftmost edge there is no neighbor and the call succeeds without changing anything.
       # @param account_id [String] account id ID
       # @param column_id [String] column id ID
       # @return [void]
       def move_column_left(account_id:, column_id:)
         with_operation(service: "miscellaneous", operation: "MoveColumnLeft", is_mutation: true, resource_id: column_id) do
-          http_post("/#{account_id}/columns/#{column_id}/left_position.json", retryable: true)
+          http_post("/#{account_id}/columns/#{column_id}/left_position.json")
           nil
         end
       end
 
-      # move_column_right operation
+      # Swaps the column with its right neighbor. Each call moves it again, so it is not idempotent; at the rightmost edge there is no neighbor and the call succeeds without changing anything.
       # @param account_id [String] account id ID
       # @param column_id [String] column id ID
       # @return [void]
       def move_column_right(account_id:, column_id:)
         with_operation(service: "miscellaneous", operation: "MoveColumnRight", is_mutation: true, resource_id: column_id) do
-          http_post("/#{account_id}/columns/#{column_id}/right_position.json", retryable: true)
+          http_post("/#{account_id}/columns/#{column_id}/right_position.json")
           nil
         end
       end
@@ -192,9 +192,9 @@ module Fizzy
 
       # update_notification_settings operation
       # @param account_id [String] account id ID
-      # @param bundle_email_frequency [String, nil] bundle email frequency
+      # @param bundle_email_frequency [String] "never", "every_few_hours", "daily" or "weekly" (User::Settings#bundle_email_frequency). Required: an empty body is a 400.
       # @return [void]
-      def update_notification_settings(account_id:, bundle_email_frequency: nil)
+      def update_notification_settings(account_id:, bundle_email_frequency:)
         with_operation(service: "miscellaneous", operation: "UpdateNotificationSettings", is_mutation: true, resource_id: account_id) do
           http_patch("/#{account_id}/notifications/settings.json", body: compact_params(bundle_email_frequency: bundle_email_frequency))
           nil
@@ -241,7 +241,7 @@ module Fizzy
       # update_user_role operation
       # @param account_id [String] account id ID
       # @param user_id [String] user id ID
-      # @param role [String] role
+      # @param role [String] "member" or "admin". Any other value, including "owner", sets the role to "member" (Users::RolesController#role_params), so a typo demotes.
       # @return [void]
       def update_user_role(account_id:, user_id:, role:)
         with_operation(service: "miscellaneous", operation: "UpdateUserRole", is_mutation: true, resource_id: user_id) do

data/lib/fizzy/generated/services/notifications_service.rb

@@ -7,20 +7,18 @@ module Fizzy
     # @generated from OpenAPI spec
     class NotificationsService < BaseService
 
-      # list operation
+      # Lists the caller's notifications. It takes no read/unread filter: the first page holds up to 100 unread notifications followed by a page of read ones, and later pages hold read ones only.
       # @param account_id [String] account id ID
-      # @param read [Boolean, nil] read
       # @return [Enumerator<Hash>] paginated results
-      def list(account_id:, read: nil)
+      def list(account_id:)
         wrap_paginated(service: "notifications", operation: "ListNotifications", is_mutation: false, resource_id: account_id) do
-          params = compact_params(read: read)
-          paginate("/#{account_id}/notifications.json", params: params)
+          paginate("/#{account_id}/notifications.json")
         end
       end
 
-      # bulk_read operation
+      # Marks every unread notification of the caller read. It takes no selection.
       # @param account_id [String] account id ID
-      # @param notification_ids [Array, nil] notification ids
+      # @param notification_ids [Array, nil] Ignored: Notifications::BulkReadingsController reads no ids and marks every unread notification read whatever this holds.
       # @return [void]
       def bulk_read(account_id:, notification_ids: nil)
         with_operation(service: "notifications", operation: "BulkReadNotifications", is_mutation: true, resource_id: account_id) do

data/lib/fizzy/generated/services/sessions_service.rb

@@ -7,7 +7,7 @@ module Fizzy
     # @generated from OpenAPI spec
     class SessionsService < BaseService
 
-      # create operation
+      # Starts a magic-link sign-in and answers the pending authentication token.
       # @param email_address [String] email address
       # @return [Hash] response data
       def create(email_address:)
@@ -25,12 +25,12 @@ module Fizzy
         end
       end
 
-      # redeem_magic_link operation
-      # @param token [String] token
+      # Redeems the code from a magic-link email for a session token.
+      # @param code [String] The code from the magic-link email.
       # @return [Hash] response data
-      def redeem_magic_link(token:)
+      def redeem_magic_link(code:)
         with_operation(service: "sessions", operation: "RedeemMagicLink", is_mutation: true) do
-          http_post("/session/magic_link.json", body: compact_params(token: token)).json
+          http_post("/session/magic_link.json", body: compact_params(code: code)).json
         end
       end
 

data/lib/fizzy/generated/services/steps_service.rb

@@ -40,7 +40,7 @@ module Fizzy
         end
       end
 
-      # update operation
+      # Updates a step. Send at least one of content or completed: the controller expects a `step` object, so an empty body is a 400.
       # @param account_id [String] account id ID
       # @param card_number [Integer] card number ID
       # @param step_id [String] step id ID

data/lib/fizzy/generated/services/users_service.rb

@@ -29,9 +29,9 @@ module Fizzy
       # update operation
       # @param account_id [String] account id ID
       # @param user_id [String] user id ID
-      # @param name [String, nil] name
+      # @param name [String] Required: the controller expects a `user` object, so an empty body is a 400.
       # @return [Hash] response data
-      def update(account_id:, user_id:, name: nil)
+      def update(account_id:, user_id:, name:)
         with_operation(service: "users", operation: "UpdateUser", is_mutation: true, resource_id: user_id) do
           http_patch("/#{account_id}/users/#{user_id}", body: compact_params(name: name)).json
         end

data/lib/fizzy/generated/services/webhooks_service.rb

@@ -7,7 +7,7 @@ module Fizzy
     # @generated from OpenAPI spec
     class WebhooksService < BaseService
 
-      # list operation
+      # Lists the board's webhooks. Fizzy pages this list (a Link header with rel="next"); this operation returns the first page.
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
       # @return [Hash] response data
@@ -22,7 +22,7 @@ module Fizzy
       # @param board_id [String] board id ID
       # @param name [String] name
       # @param url [String] url
-      # @param subscribed_actions [Array, nil] subscribed actions
+      # @param subscribed_actions [Array, nil] The events to deliver, from: "card_assigned", "card_closed", "card_postponed", "card_auto_postponed", "card_board_changed", "card_published", "card_reopened", "card_sent_back_to_triage", "card_triaged", "card_unassigned" and "comment_created" (Webhook::PERMITTED_ACTIONS). Unknown actions are dropped silently. A webhook created without any receives no deliveries.
       # @return [Hash] response data
       def create(account_id:, board_id:, name:, url:, subscribed_actions: nil)
         with_operation(service: "webhooks", operation: "CreateWebhook", is_mutation: true, resource_id: board_id) do
@@ -41,17 +41,16 @@ module Fizzy
         end
       end
 
-      # update operation
+      # Updates a webhook's name or subscribed actions. Send at least one: the controller expects a `webhook` object, so an empty body is a 400. The URL can't change after creation; delete the webhook and create a new one.
       # @param account_id [String] account id ID
       # @param board_id [String] board id ID
       # @param webhook_id [String] webhook id ID
       # @param name [String, nil] name
-      # @param url [String, nil] url
-      # @param subscribed_actions [Array, nil] subscribed actions
+      # @param subscribed_actions [Array, nil] The events to deliver, from: "card_assigned", "card_closed", "card_postponed", "card_auto_postponed", "card_board_changed", "card_published", "card_reopened", "card_sent_back_to_triage", "card_triaged", "card_unassigned" and "comment_created" (Webhook::PERMITTED_ACTIONS). Unknown actions are dropped silently. The list replaces the current subscription.
       # @return [Hash] response data
-      def update(account_id:, board_id:, webhook_id:, name: nil, url: nil, subscribed_actions: nil)
+      def update(account_id:, board_id:, webhook_id:, name: nil, subscribed_actions: nil)
         with_operation(service: "webhooks", operation: "UpdateWebhook", is_mutation: true, resource_id: webhook_id) do
-          http_patch("/#{account_id}/boards/#{board_id}/webhooks/#{webhook_id}", body: compact_params(name: name, url: url, subscribed_actions: subscribed_actions)).json
+          http_patch("/#{account_id}/boards/#{board_id}/webhooks/#{webhook_id}", body: compact_params(name: name, subscribed_actions: subscribed_actions)).json
         end
       end
 

data/lib/fizzy/generated/types.rb

@@ -365,16 +365,13 @@ module Fizzy
     CreateCardReactionResponseContent = Data.define
 
     # @generated
-    CreateCardRequestContent = Data.define(:title, :board_id, :column_id, :description, :assignee_ids, :tag_names, :image, :created_at, :last_active_at) do
+    CreateCardRequestContent = Data.define(:title, :board_id, :description, :image, :created_at, :last_active_at) do
       # @param data [Hash] raw JSON response
       def self.from_json(data)
         new(
           title: data["title"],
           board_id: data["board_id"],
-          column_id: data["column_id"],
           description: data["description"],
-          assignee_ids: data["assignee_ids"],
-          tag_names: data["tag_names"],
           image: data["image"],
           created_at: data["created_at"],
           last_active_at: data["last_active_at"]
@@ -700,12 +697,11 @@ module Fizzy
     ListWebhooksResponseContent = Data.define
 
     # @generated
-    MoveCardRequestContent = Data.define(:board_id, :column_id) do
+    MoveCardRequestContent = Data.define(:board_id) do
       # @param data [Hash] raw JSON response
       def self.from_json(data)
         new(
-          board_id: data["board_id"],
-          column_id: data["column_id"]
+          board_id: data["board_id"]
         )
       end
     end
@@ -805,11 +801,11 @@ module Fizzy
     end
 
     # @generated
-    RedeemMagicLinkRequestContent = Data.define(:token) do
+    RedeemMagicLinkRequestContent = Data.define(:code) do
       # @param data [Hash] raw JSON response
       def self.from_json(data)
         new(
-          token: data["token"]
+          code: data["code"]
         )
       end
     end
@@ -986,13 +982,12 @@ module Fizzy
     UpdateBoardResponseContent = Data.define
 
     # @generated
-    UpdateCardRequestContent = Data.define(:title, :description, :column_id, :image, :created_at) do
+    UpdateCardRequestContent = Data.define(:title, :description, :image, :created_at) do
       # @param data [Hash] raw JSON response
       def self.from_json(data)
         new(
           title: data["title"],
           description: data["description"],
-          column_id: data["column_id"],
           image: data["image"],
           created_at: data["created_at"]
         )
@@ -1097,12 +1092,11 @@ module Fizzy
     end
 
     # @generated
-    UpdateWebhookRequestContent = Data.define(:name, :url, :subscribed_actions) do
+    UpdateWebhookRequestContent = Data.define(:name, :subscribed_actions) do
       # @param data [Hash] raw JSON response
       def self.from_json(data)
         new(
           name: data["name"],
-          url: data["url"],
           subscribed_actions: data["subscribed_actions"]
         )
       end

data/lib/fizzy/http.rb

@@ -160,12 +160,15 @@ module Fizzy
     end
 
     def request_with_retry(method, url, params: {}, body: nil)
+      # max_retries counts total attempts and is floored at one: whether a
+      # request reaches the wire at all must not depend on the retry budget.
+      max_attempts = [ @config.max_retries, 1 ].max
       attempt = 0
       last_error = nil
 
       loop do
         attempt += 1
-        break if attempt > @config.max_retries
+        break if attempt > max_attempts
 
         begin
           return single_request(method, url, params: params, body: body, attempt: attempt)
@@ -175,7 +178,7 @@ module Fizzy
           last_error = e
 
           # Don't sleep if this was the last attempt
-          break if attempt >= @config.max_retries
+          break if attempt >= max_attempts
 
           delay = calculate_delay(attempt, e.retry_after)
 
@@ -187,7 +190,8 @@ module Fizzy
         end
       end
 
-      raise last_error || Fizzy::APIError.new("Request failed after #{@config.max_retries} retries")
+      noun = max_attempts == 1 ? "attempt" : "attempts"
+      raise last_error || Fizzy::APIError.new("Request failed after #{max_attempts} #{noun}")
     end
 
     def single_request(method, url, params:, body:, attempt:, retry_count: 0)
@@ -210,6 +214,10 @@ module Fizzy
           status: response.status,
           headers: response.headers
         )
+      rescue Faraday::TimeoutError => e
+        # Faraday::TimeoutError < Faraday::ServerError: named before the status
+        # clause, or a stalled read classifies as a status-less api_error.
+        transport_failure(e, info: info, start_time: start_time)
       rescue Faraday::ServerError, Faraday::ClientError => e
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
         error = handle_error(e)
@@ -229,11 +237,7 @@ module Fizzy
 
         raise error
       rescue Faraday::Error => e
-        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        error = Fizzy::NetworkError.new("Connection failed", cause: e)
-        result = RequestResult.new(duration: duration, error: error)
-        @hooks.on_request_end(info, result)
-        raise error
+        transport_failure(e, info: info, start_time: start_time)
       end
     end
 
@@ -265,6 +269,8 @@ module Fizzy
           status: response.status,
           headers: response.headers
         )
+      rescue Faraday::TimeoutError => e
+        transport_failure(e, info: info, start_time: start_time)
       rescue Faraday::ServerError, Faraday::ClientError => e
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
         error = handle_error(e)
@@ -277,14 +283,21 @@ module Fizzy
         @hooks.on_request_end(info, result)
         raise error
       rescue Faraday::Error => e
-        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        error = Fizzy::NetworkError.new("Connection failed", cause: e)
-        result = RequestResult.new(duration: duration, error: error)
-        @hooks.on_request_end(info, result)
-        raise error
+        transport_failure(e, info: info, start_time: start_time)
       end
     end
 
+    # A transport failure — no HTTP response, so no status to map — as the
+    # network error the caller and on_request_end both see: a timeout by name,
+    # anything else as a connection failure, both retryable.
+    def transport_failure(exception, info:, start_time:)
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      message = exception.is_a?(Faraday::TimeoutError) ? "Request timed out" : "Connection failed"
+      error = Fizzy::NetworkError.new(message, cause: exception)
+      @hooks.on_request_end(info, RequestResult.new(duration: duration, error: error))
+      raise error
+    end
+
     def handle_error(error)
       status = error.response&.dig(:status)
       body = error.response&.dig(:body)

data/lib/fizzy/magic_link_flow.rb

@@ -1,56 +1,120 @@
 # frozen_string_literal: true
 
 module Fizzy
-  # Orchestrates the passwordless magic link authentication flow.
+  # Signs in without a password. Fizzy emails a code to an address and, once the person types
+  # it back, hands out a session token for {CookieAuth}.
   #
-  # The flow works in two steps:
-  # 1. Call CreateSession with an email address - this sends a magic link email
-  # 2. Call RedeemMagicLink with the token from the magic link URL
+  # The two steps are one exchange as far as Fizzy is concerned: creating the session sets a
+  # +pending_authentication_token+ cookie naming the address the code went to, and redeeming
+  # the code has to send that cookie back or the code is refused. The flow keeps the token
+  # between the calls, and hands it out for a caller that finishes in another process (a CLI
+  # that prompts for the code on its next run), which picks it up again with +pending_token:+.
   #
-  # After redemption, the response contains a session token that can be used
-  # with CookieAuth or BearerAuth for subsequent requests.
+  # Both requests go through the generated {Services::SessionsService}, so their paths and
+  # bodies are the model's: +POST /session.json+ with +email_address+, then
+  # +POST /session/magic_link.json+ with +code+.
   #
   # @example
-  #   flow = Fizzy::MagicLinkFlow.new(base_url: "https://fizzy.do")
-  #   flow.request_magic_link(email: "user@example.com")
-  #   # User clicks magic link in email, your app extracts the token
-  #   session = flow.redeem(token: "magic-link-token-from-url")
-  #   # Use session token for authenticated requests
+  #   flow = Fizzy::MagicLinkFlow.new
+  #   flow.create_session(email_address: "jane@example.com")
+  #   # ... the person reads the code out of their email ...
+  #   session = flow.redeem(code: "ABC123")
   #   client = Fizzy.client(auth: Fizzy::CookieAuth.new(session["session_token"]))
+  #
+  # @example Finishing in another process
+  #   pending = Fizzy::MagicLinkFlow.new.tap { _1.create_session(email_address: email) }.pending_token
+  #   # ... later ...
+  #   Fizzy::MagicLinkFlow.new(pending_token: pending).redeem(code: code)
   class MagicLinkFlow
+    # The cookie a pending sign-in is carried in between creating the session and redeeming
+    # the code.
+    PENDING_COOKIE = "pending_authentication_token"
+
+    # The token a pending sign-in is waiting on, for a caller that finishes the flow in
+    # another process.
+    # @return [String, nil]
+
     # @param base_url [String] Fizzy API base URL
     # @param hooks [Hooks, nil] observability hooks
-    def initialize(base_url: Config::DEFAULT_BASE_URL, hooks: nil)
+    # @param pending_token [String, nil] the pending token of a sign-in another flow started
+    def initialize(base_url: Config::DEFAULT_BASE_URL, hooks: nil, pending_token: nil)
+      @pending_token = pending_token
+      @lock = Mutex.new
       @config = Config.new(base_url: base_url)
-      @hooks = hooks || NoopHooks.new
-      @http = Http.new(config: @config, auth_strategy: NullAuth.new, hooks: @hooks)
+      @hooks = hooks
+      @client = client_with(PendingCookieAuth.new(nil))
+    end
+
+    # The pending authentication token of the sign-in under way, or nil before one starts.
+    # @return [String, nil]
+    def pending_token
+      @lock.synchronize { @pending_token }
     end
 
-    # Step 1: Request a magic link email.
+    # Asks Fizzy to email a sign-in code to the address, and keeps the pending token the
+    # answer carries for {#redeem}.
     #
-    # @param email [String] the user's email address
-    # @return [Hash] response from the API
-    def request_magic_link(email:)
-      response = @http.post("/sessions", body: { email: email })
-      response.json
+    # @param email_address [String] the address to send the code to
+    # @return [String] the pending authentication token
+    # @raise [APIError] when Fizzy answers without a pending token
+    def create_session(email_address:)
+      answer = @client.sessions.create(email_address: email_address)
+      token = answer.is_a?(Hash) ? answer["pending_authentication_token"] : nil
+      raise APIError.new("Fizzy answered no pending authentication token") \
+        unless token.is_a?(String) && !token.empty?
+
+      @lock.synchronize { @pending_token = token }
     end
 
-    # Step 2: Redeem a magic link token to get a session.
+    # Redeems the code from the email, sending back the pending token as the cookie Fizzy
+    # reads it from.
     #
-    # @param token [String] the magic link token from the URL
-    # @return [Hash] response containing session_token and user info
-    def redeem(token:)
-      response = @http.post("/sessions/redeem", body: { token: token })
-      response.json
+    # @param code [String] the code from the magic-link email
+    # @return [Hash] +session_token+ and +requires_signup_completion+
+    # @raise [UsageError] when no sign-in is pending
+    # @raise [AuthError] when Fizzy refuses the code or the pending token
+    def redeem(code:)
+      pending = pending_token
+      raise UsageError.new("no sign-in is pending; call create_session first, or pass pending_token:") \
+        if pending.nil? || pending.empty?
+
+      # The cookie is bound to the token read here, so a sign-in that starts while this one is
+      # under way (a hook can yield before the request is signed) cannot pair this code with
+      # another's pending token.
+      answer = client_with(PendingCookieAuth.new(pending)).sessions.redeem_magic_link(code: code)
+      raise APIError.new("Fizzy answered no session token") \
+        unless answer.is_a?(Hash) && answer["session_token"].is_a?(String)
+
+      # The sign-in redeemed is consumed; one a create_session started meanwhile is not.
+      @lock.synchronize { @pending_token = nil if @pending_token.equal?(pending) }
+      answer.slice("session_token", "requires_signup_completion")
     end
 
-    # Null authentication strategy for unauthenticated requests.
+    # A +Cookie+ header value carrying one cookie, its value percent-encoded as Rack decodes it.
     # @api private
-    class NullAuth
+    def self.cookie(name, value)
+      encoded = value.to_s.b.gsub(/[^A-Za-z0-9\-_.~]/n) { |byte| format("%%%02X", byte.ord) }
+      "#{name}=#{encoded}"
+    end
+
+    private
+
+    def client_with(auth_strategy)
+      Client.new(config: @config, auth_strategy: auth_strategy, hooks: @hooks)
+    end
+
+    # Sends one pending token, when given one, as the cookie Fizzy reads the pending sign-in
+    # from, and no other credentials: there are none yet.
+    # @api private
+    class PendingCookieAuth
       include AuthStrategy
 
+      def initialize(token)
+        @token = token
+      end
+
       def authenticate(headers)
-        # No authentication needed for magic link flow initiation
+        headers["Cookie"] = MagicLinkFlow.cookie(PENDING_COOKIE, @token) unless @token.nil? || @token.empty?
       end
     end
   end

data/lib/fizzy/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Fizzy
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
   API_VERSION = "2026-03-01"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fizzy-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday