appwrite 26.0.0 → 26.1.0

data/lib/appwrite/services/backups.rb

@@ -317,24 +317,38 @@ module Appwrite
 
         # Create and trigger a new restoration for a backup on a project.
         # 
-        # When restoring a DocumentsDB or VectorsDB database to a new resource, pass
-        # `newSpecification` to provision the restored database on a different
-        # specification than the archived one (for example, restoring onto a larger
-        # or smaller dedicated database). Use `serverless` to restore onto the shared
-        # pool, or a dedicated specification slug to restore onto a dedicated
-        # database of that size. The specification must be permitted by the
-        # organization's plan. `newSpecification` is not supported for
-        # legacy/TablesDB databases or for bucket restores.
+        # For a backup of one database, the restoration resolves its destination
+        # before it is queued. Pass `newResourceId` to restore into that database ID,
+        # including the archived database ID to overwrite it. When `newResourceId` is
+        # omitted, a new database ID is generated and returned in `options`.
+        # 
+        # The restoration migration records the archived database in `resourceId` and
+        # `resourceType`, and the resolved database in `destinationResourceId` and
+        # `destinationResourceType`. Database types are stored canonically as
+        # `database`, `documentsdb`, or `vectorsdb`. Project-wide restorations leave
+        # these fields empty because they do not have a single source or destination
+        # database.
+        # 
+        # To list every migration related to one database, use its canonical type in
+        # a nested `OR(AND(...), AND(...), AND(...))` across the root, parent, and
+        # destination relation pairs: `(resourceType, resourceId)`,
+        # `(parentResourceType, parentResourceId)`, and `(destinationResourceType,
+        # destinationResourceId)`. Legacy and TablesDB databases use `database`; the
+        # operational `resourceType` of a table migration is not rewritten to
+        # `tablesdb`.
+        # 
+        # When restoring a DocumentsDB or VectorsDB database to a new resource from a
+        # dedicated source, the restore provisions a fresh dedicated backing database
+        # at the source database's own specification.
         # 
         #
         # @param [String] archive_id Backup archive ID to restore
         # @param [Array] services Array of services to restore
-        # @param [String] new_resource_id Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
+        # @param [String] new_resource_id Destination resource ID. Omit to generate a new ID, or pass the archived resource ID to overwrite it. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
         # @param [String] new_resource_name Database name. Max length: 128 chars.
-        # @param [String] new_specification Specification to provision the restored database on, when restoring a DocumentsDB or VectorsDB database to a new resource. Defaults to the archived database's specification. Use `serverless` for the shared pool or a dedicated specification slug.
         #
         # @return [BackupRestoration]
-        def create_restoration(archive_id:, services:, new_resource_id: nil, new_resource_name: nil, new_specification: nil)
+        def create_restoration(archive_id:, services:, new_resource_id: nil, new_resource_name: nil)
             api_path = '/backups/restoration'
 
             if archive_id.nil?
@@ -350,7 +364,6 @@ module Appwrite
                 services: services,
                 newResourceId: new_resource_id,
                 newResourceName: new_resource_name,
-                newSpecification: new_specification,
             }
             
             api_headers = {

data/lib/appwrite/services/oauth2.rb

@@ -0,0 +1,525 @@
+#frozen_string_literal: true
+
+module Appwrite
+    class Oauth2 < Service
+
+        def initialize(client)
+            @client = client
+        end
+
+        # Approve an OAuth2 grant after the user gives consent. Returns the
+        # `redirectUrl` the end user should be sent to. The consent screen may
+        # optionally pass enriched `authorization_details` to record the concrete
+        # resources the user selected. You can pass Accept header of
+        # `application/json` to receive a JSON response instead of a redirect.
+        #
+        # @param [String] grant_id Grant ID made during authorization, provided to consent screen in URL search params.
+        # @param [String] authorization_details Enriched `authorization_details` the user consented to, replacing what the client requested. Each entry must use a `type` the project accepts. Optional; omit to keep the originally requested details.
+        # @param [String] scope Space-separated scopes the user consented to. Must be a subset of the scopes originally requested; identity scopes such as `openid` are always retained. Optional; omit to keep the originally requested scopes.
+        #
+        # @return [Oauth2Approve]
+        def approve(grant_id:, authorization_details: nil, scope: nil)
+            api_path = '/oauth2/{project_id}/approve'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            if grant_id.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "grantId"')
+            end
+
+            api_params = {
+                grant_id: grant_id,
+                authorization_details: authorization_details,
+                scope: scope,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Approve
+            )
+
+        end
+
+        # Begin the OAuth2 authorization flow. When called without a session, the
+        # user is redirected to the consent screen without grant ID. When called with
+        # a session, the redirect URL includes param for grant ID. You can pass
+        # Accept header of `application/json` to receive a JSON response instead of a
+        # redirect.
+        #
+        # @param [String] client_id OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
+        # @param [String] redirect_uri Redirect URI where visitor will be redirected after authorization, whether successful or not.
+        # @param [String] response_type OAuth2 / OIDC response type. One of `code` (Authorization Code Flow), `id_token` (Implicit Flow, OIDC login only), or `code id_token` (Hybrid Flow).
+        # @param [String] scope Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`, `phone`.
+        # @param [String] state OAuth2 state. You receive this back in the redirect URI.
+        # @param [String] nonce OIDC nonce parameter to prevent replay attacks. Required when response_type includes `id_token`.
+        # @param [String] code_challenge PKCE code challenge. Required when OAuth2 app is public.
+        # @param [String] code_challenge_method PKCE code challenge method. Required when OAuth2 app is public.
+        # @param [String] prompt OIDC prompt parameter for customization of consent screen. Space-separated list of: none, login, consent, select_account.
+        # @param [Integer] max_age OIDC max_age paraleter for customization of consent screen. Maximum allowable elapsed time in seconds since the user last authenticated. If exceeded, re-authentication is required.
+        # @param [String] authorization_details Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
+        # @param [String] resource RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
+        # @param [String] audience Compatibility alias for a single OAuth2 resource indicator URI.
+        # @param [String] request_uri OAuth2 authorization request handle returned by the pushed authorization request endpoint.
+        #
+        # @return [Oauth2Authorize]
+        def authorize(client_id: nil, redirect_uri: nil, response_type: nil, scope: nil, state: nil, nonce: nil, code_challenge: nil, code_challenge_method: nil, prompt: nil, max_age: nil, authorization_details: nil, resource: nil, audience: nil, request_uri: nil)
+            api_path = '/oauth2/{project_id}/authorize'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            api_params = {
+                client_id: client_id,
+                redirect_uri: redirect_uri,
+                response_type: response_type,
+                scope: scope,
+                state: state,
+                nonce: nonce,
+                code_challenge: code_challenge,
+                code_challenge_method: code_challenge_method,
+                prompt: prompt,
+                max_age: max_age,
+                authorization_details: authorization_details,
+                resource: resource,
+                audience: audience,
+                request_uri: request_uri,
+            }
+            
+            api_headers = {
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'GET',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Authorize
+            )
+
+        end
+
+        # Begin the OAuth2 authorization flow. When called without a session, the
+        # user is redirected to the consent screen without grant ID. When called with
+        # a session, the redirect URL includes param for grant ID. You can pass
+        # Accept header of `application/json` to receive a JSON response instead of a
+        # redirect.
+        #
+        # @param [String] client_id OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
+        # @param [String] redirect_uri Redirect URI where visitor will be redirected after authorization, whether successful or not.
+        # @param [String] response_type OAuth2 / OIDC response type. One of `code` (Authorization Code Flow), `id_token` (Implicit Flow, OIDC login only), or `code id_token` (Hybrid Flow).
+        # @param [String] scope Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`, `phone`.
+        # @param [String] state OAuth2 state. You receive this back in the redirect URI.
+        # @param [String] nonce OIDC nonce parameter to prevent replay attacks. Required when response_type includes `id_token`.
+        # @param [String] code_challenge PKCE code challenge. Required when OAuth2 app is public.
+        # @param [String] code_challenge_method PKCE code challenge method. Required when OAuth2 app is public.
+        # @param [String] prompt OIDC prompt parameter for customization of consent screen. Space-separated list of: none, login, consent, select_account.
+        # @param [Integer] max_age OIDC max_age paraleter for customization of consent screen. Maximum allowable elapsed time in seconds since the user last authenticated. If exceeded, re-authentication is required.
+        # @param [String] authorization_details Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
+        # @param [String] resource RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
+        # @param [String] audience Compatibility alias for a single OAuth2 resource indicator URI.
+        # @param [String] request_uri OAuth2 authorization request handle returned by the pushed authorization request endpoint.
+        #
+        # @return [Oauth2Authorize]
+        def authorize_post(client_id: nil, redirect_uri: nil, response_type: nil, scope: nil, state: nil, nonce: nil, code_challenge: nil, code_challenge_method: nil, prompt: nil, max_age: nil, authorization_details: nil, resource: nil, audience: nil, request_uri: nil)
+            api_path = '/oauth2/{project_id}/authorize'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            api_params = {
+                client_id: client_id,
+                redirect_uri: redirect_uri,
+                response_type: response_type,
+                scope: scope,
+                state: state,
+                nonce: nonce,
+                code_challenge: code_challenge,
+                code_challenge_method: code_challenge_method,
+                prompt: prompt,
+                max_age: max_age,
+                authorization_details: authorization_details,
+                resource: resource,
+                audience: audience,
+                request_uri: request_uri,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Authorize
+            )
+
+        end
+
+        # Start the OAuth2 Device Authorization Grant. Returns the device code, user
+        # code, verification URL, expiration, and polling interval.
+        #
+        # @param [String] client_id OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
+        # @param [String] scope Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`.
+        # @param [String] authorization_details Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
+        # @param [String] resource RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
+        # @param [String] audience Compatibility alias for a single OAuth2 resource indicator URI.
+        #
+        # @return [Oauth2DeviceAuthorization]
+        def create_device_authorization(client_id: nil, scope: nil, authorization_details: nil, resource: nil, audience: nil)
+            api_path = '/oauth2/{project_id}/device_authorization'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            api_params = {
+                client_id: client_id,
+                scope: scope,
+                authorization_details: authorization_details,
+                resource: resource,
+                audience: audience,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2DeviceAuthorization
+            )
+
+        end
+
+        # Exchange a device flow user code for an OAuth2 grant. The authenticated
+        # user is bound to the pending grant. Pass the returned grant ID to the get
+        # grant endpoint to render the consent screen, then to the approve or reject
+        # endpoint to complete the flow.
+        #
+        # @param [String] user_code User code displayed on the device.
+        #
+        # @return [Oauth2Grant]
+        def create_grant(user_code:)
+            api_path = '/oauth2/{project_id}/grants'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            if user_code.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "userCode"')
+            end
+
+            api_params = {
+                user_code: user_code,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Grant
+            )
+
+        end
+
+        # Get an OAuth2 grant by its ID. Used by the consent screen to display the
+        # details of the authorization the user is being asked to approve. A grant
+        # can only be read by the user it belongs to, or by server SDK.
+        #
+        # @param [String] grant_id Grant ID made during authorization, provided to consent screen in URL search params.
+        #
+        # @return [Oauth2Grant]
+        def get_grant(grant_id:)
+            api_path = '/oauth2/{project_id}/grants/{grant_id}'
+                .gsub('{project_id}', @client.get_config('project'))
+                .gsub('{grant_id}', grant_id)
+
+            if grant_id.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "grantId"')
+            end
+
+            api_params = {
+            }
+            
+            api_headers = {
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'GET',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Grant
+            )
+
+        end
+
+        # List the organizations the OAuth2 access token can access. Resolves the
+        # token's `organization` authorization details, expanding the `*` wildcard
+        # into the concrete set of organizations the user can see.
+        #
+        # @param [Integer] limit Maximum number of organizations to return. Between 1 and 5000.
+        # @param [Integer] offset Number of organizations to skip before returning results. Used for pagination.
+        # @param [String] search Search term to filter your list results. Max length: 256 chars.
+        #
+        # @return [Oauth2OrganizationList]
+        def list_organizations(limit: nil, offset: nil, search: nil)
+            api_path = '/oauth2/{project_id}/organizations'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            api_params = {
+                limit: limit,
+                offset: offset,
+                search: search,
+            }
+            
+            api_headers = {
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'GET',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2OrganizationList
+            )
+
+        end
+
+        # Store an OAuth2 authorization request server-side and receive a short-lived
+        # request_uri handle for the authorize endpoint.
+        #
+        # @param [String] client_id OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
+        # @param [String] redirect_uri Redirect URI where visitor will be redirected after authorization, whether successful or not.
+        # @param [String] response_type OAuth2 / OIDC response type.
+        # @param [String] scope Space-separated OAuth2 scopes. Can include project scopes, and built-in scopes: `openid`, `email`, `profile`, `phone`.
+        # @param [String] state OAuth2 state. You receive this back in the redirect URI.
+        # @param [String] nonce OIDC nonce parameter to prevent replay attacks. Required when response_type includes `id_token`.
+        # @param [String] code_challenge PKCE code challenge. Required when OAuth2 app is public.
+        # @param [String] code_challenge_method PKCE code challenge method. Required when OAuth2 app is public.
+        # @param [String] prompt OIDC prompt parameter for customization of consent screen. Space-separated list of: none, login, consent, select_account.
+        # @param [Integer] max_age OIDC max_age parameter for customization of consent screen.
+        # @param [String] authorization_details Rich authorization request. JSON array of objects, each with a `type` and project-defined fields
+        # @param [String] resource RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
+        # @param [String] audience Compatibility alias for a single OAuth2 resource indicator URI.
+        #
+        # @return [Oauth2PAR]
+        def create_par(client_id:, redirect_uri:, response_type:, scope: nil, state: nil, nonce: nil, code_challenge: nil, code_challenge_method: nil, prompt: nil, max_age: nil, authorization_details: nil, resource: nil, audience: nil)
+            api_path = '/oauth2/{project_id}/par'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            if client_id.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "clientId"')
+            end
+
+            if redirect_uri.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "redirectUri"')
+            end
+
+            if response_type.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "responseType"')
+            end
+
+            api_params = {
+                client_id: client_id,
+                redirect_uri: redirect_uri,
+                response_type: response_type,
+                scope: scope,
+                state: state,
+                nonce: nonce,
+                code_challenge: code_challenge,
+                code_challenge_method: code_challenge_method,
+                prompt: prompt,
+                max_age: max_age,
+                authorization_details: authorization_details,
+                resource: resource,
+                audience: audience,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2PAR
+            )
+
+        end
+
+        # List the projects the OAuth2 access token can access. Resolves the token's
+        # `project` authorization details, expanding the `*` wildcard into the
+        # concrete set of projects the user can see.
+        #
+        # @param [Integer] limit Maximum number of projects to return. Between 1 and 5000.
+        # @param [Integer] offset Number of projects to skip before returning results. Used for pagination.
+        # @param [String] search Search term to filter your list results. Max length: 256 chars.
+        #
+        # @return [Oauth2ProjectList]
+        def list_projects(limit: nil, offset: nil, search: nil)
+            api_path = '/oauth2/{project_id}/projects'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            api_params = {
+                limit: limit,
+                offset: offset,
+                search: search,
+            }
+            
+            api_headers = {
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'GET',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2ProjectList
+            )
+
+        end
+
+        # Reject an OAuth2 grant when the user denies consent. Returns the
+        # `redirectUrl` the end user should be sent to with an `access_denied` error.
+        # You can pass Accept header of `application/json` to receive a JSON response
+        # instead of a redirect.
+        #
+        # @param [String] grant_id Grant ID made during authorization, provided to consent screen in URL search params.
+        #
+        # @return [Oauth2Reject]
+        def reject(grant_id:)
+            api_path = '/oauth2/{project_id}/reject'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            if grant_id.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "grantId"')
+            end
+
+            api_params = {
+                grant_id: grant_id,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Reject
+            )
+
+        end
+
+        # Revoke an OAuth2 access token or refresh token.
+        #
+        # @param [String] token The access or refresh token to revoke.
+        # @param [String] token_type_hint Type of token to revoke (access_token or refresh_token).
+        # @param [String] client_id OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
+        # @param [String] client_secret OAuth2 client secret. Required for confidential apps; omitted for public apps.
+        #
+        # @return []
+        def revoke(token:, token_type_hint: nil, client_id: nil, client_secret: nil)
+            api_path = '/oauth2/{project_id}/revoke'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            if token.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "token"')
+            end
+
+            api_params = {
+                token: token,
+                token_type_hint: token_type_hint,
+                client_id: client_id,
+                client_secret: client_secret,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+            )
+
+        end
+
+        # Exchange an OAuth2 authorization code, refresh token, or device code for
+        # access and refresh tokens.
+        #
+        # @param [String] grant_type OAuth2 grant type. Can be one of: `authorization_code`, `refresh_token`, `urn:ietf:params:oauth:grant-type:device_code`.
+        # @param [String] code Authorization code to be exchanged for access and refresh tokens. Required for `authorization_code` grant type.
+        # @param [String] refresh_token Refresh token to be exchanged for a new access and refresh tokens. Required for `refresh_token` grant type.
+        # @param [String] device_code Device code obtained from the device authorization endpoint. Required for `urn:ietf:params:oauth:grant-type:device_code` grant type.
+        # @param [String] client_id OAuth2 client ID. Either a registered app ID or an HTTPS client ID metadata document URL.
+        # @param [String] client_secret OAuth2 client secret. Required for confidential apps.
+        # @param [String] code_verifier PKCE code verifier. Required for public apps.
+        # @param [String] redirect_uri Redirect URI. Required for `authorization_code` grant type.
+        # @param [String] resource RFC 8707 resource indicator URI or URI list. Each value must be an absolute URI without a fragment.
+        # @param [String] audience Compatibility alias for a single OAuth2 resource indicator URI.
+        #
+        # @return [Oauth2Token]
+        def create_token(grant_type:, code: nil, refresh_token: nil, device_code: nil, client_id: nil, client_secret: nil, code_verifier: nil, redirect_uri: nil, resource: nil, audience: nil)
+            api_path = '/oauth2/{project_id}/token'
+                .gsub('{project_id}', @client.get_config('project'))
+
+            if grant_type.nil?
+              raise Appwrite::Exception.new('Missing required parameter: "grantType"')
+            end
+
+            api_params = {
+                grant_type: grant_type,
+                code: code,
+                refresh_token: refresh_token,
+                device_code: device_code,
+                client_id: client_id,
+                client_secret: client_secret,
+                code_verifier: code_verifier,
+                redirect_uri: redirect_uri,
+                resource: resource,
+                audience: audience,
+            }
+            
+            api_headers = {
+                "content-type": 'application/json',
+                "accept": 'application/json',
+            }
+
+            @client.call(
+                method: 'POST',
+                path: api_path,
+                headers: api_headers,
+                params: api_params,
+                response_type: Models::Oauth2Token
+            )
+
+        end
+
+    end 
+end