Add docs and changelog

Author: zzooeeyy

CHANGELOG.md

@@ -3,6 +3,8 @@
 Note: For changes to the API, see https://shopify.dev/changelog?filter=api
 ## Unreleased
 
+- Add support for expiring offline access tokens with refresh tokens. See [OAuth documentation](docs/usage/oauth.md#expiring-offline-access-tokens) for details.
+
 ### 15.0.0
 
 - ⚠️ [Breaking] Removed deprecated `ShopifyAPI::Webhooks::Handler` interface. Apps must migrate to `ShopifyAPI::Webhooks::WebhookHandler` which provides `webhook_id` and `api_version` in addition to `topic`, `shop`, and `body`. See [BREAKING_CHANGES_FOR_V15.md](BREAKING_CHANGES_FOR_V15.md) for migration guide.

docs/getting_started.md

@@ -28,7 +28,8 @@ ShopifyAPI::Context.setup(
   scope: "read_orders,read_products,etc",
   is_embedded: true, # Set to true if you are building an embedded app
   is_private: false, # Set to true if you are building a private app
-  api_version: "2021-01" # The version of the API you would like to use
+  api_version: "2021-01", # The version of the API you would like to use
+  expiring_offline_access_tokens: true # Set to true to enable expiring offline access tokens with refresh tokens
 )
 ```
 

docs/usage/oauth.md

@@ -13,6 +13,9 @@ For more information on authenticating a Shopify app please see the [Types of Au
   - [Token Exchange](#token-exchange)
   - [Authorization Code Grant](#authorization-code-grant)
   - [Client Credentials Grant](#client-credentials-grant)
+- [Expiring Offline Access Tokens](#expiring-offline-access-tokens)
+  - [Enabling Expiring Offline Access Tokens](#enabling-expiring-offline-access-tokens)
+  - [Refreshing Access Tokens](#refreshing-access-tokens)
 - [Using OAuth Session to make authenticated API calls](#using-oauth-session-to-make-authenticated-api-calls)
 
 ## Session Persistence
@@ -305,6 +308,85 @@ end
 
 ```
 
+## Expiring Offline Access Tokens
+
+
+To start requesting expiring offline access tokens, set the `expiring_offline_access_tokens` parameter to `true` when setting up the Shopify context:
+
+```ruby
+ShopifyAPI::Context.setup(
+  api_key: <SHOPIFY_API_KEY>,
+  api_secret_key: <SHOPIFY_API_SECRET>,
+  api_version: <SHOPIFY_API_VERSION>,
+  scope: <SHOPIFY_API_SCOPES>,
+  expiring_offline_access_tokens: true, # Enable expiring offline access tokens
+  ...
+)
+```
+
+When enabled:
+- **Authorization Code Grant**: The OAuth flow will request expiring offline access tokens by sending `expiring: 1` parameter
+- **Token Exchange**: When requesting offline access tokens via token exchange, the flow will request expiring tokens
+
+The resulting `Session` object will contain:
+- `access_token`: The access token that will eventually expire
+- `expires`: The expiration time for the access token
+- `refresh_token`: A token that can be used to refresh the access token
+- `refresh_token_expires`: The expiration time for the refresh token
+
+### Refreshing Access Tokens
+
+When your access token expires, you can use the refresh token to obtain a new access token using the `ShopifyAPI::Auth::RefreshToken.refresh_access_token` method.
+
+#### Input
+| Parameter      | Type     | Required? | Notes                                                                                           |
+| -------------- | -------- | :-------: | ----------------------------------------------------------------------------------------------- |
+| `shop`         | `String` | Yes       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                               |
+| `refresh_token`| `String` | Yes       | The refresh token from the session.                                                             |
+
+#### Output
+This method returns a new `ShopifyAPI::Auth::Session` object with a fresh access token and a new refresh token. Your app should store this new session to replace the expired one.
+
+#### Example
+```ruby
+def refresh_session(shop, refresh_token)
+  begin
+    # Refresh the access token using the refresh token
+    new_session = ShopifyAPI::Auth::RefreshToken.refresh_access_token(
+      shop: shop,
+      refresh_token: refresh_token
+    )
+
+    # Store the new session, replacing the old one
+    MyApp::SessionRepository.store_shop_session(new_session)
+  rescue ShopifyAPI::Errors::HttpResponseError => e
+    puts("Failed to refresh access token: #{e.message}")
+    raise e
+  end
+end
+```
+#### Checking Token Expiration
+The `Session` object provides helper methods to check if tokens have expired:
+
+```ruby
+session = MyApp::SessionRepository.retrieve_shop_session_by_shopify_domain(shop)
+
+# Check if the access token has expired
+if session.expired?
+  # Access token has expired, refresh it
+  new_session = ShopifyAPI::Auth::RefreshToken.refresh_access_token(
+    shop: session.shop,
+    refresh_token: session.refresh_token
+  )
+  MyApp::SessionRepository.store_shop_session(new_session)
+end
+
+# Check if the refresh token has expired
+if session.refresh_token_expired?
+  # Refresh token has expired, need to re-authenticate with OAuth
+end
+```
+
 ## Using OAuth Session to make authenticated API calls
 Once your OAuth flow is complete, and you have persisted your `Session` object, you may use that `Session` object to make authenticated API calls.