feat(declarative): add OpaqueTokenCursor for opaque server-issued sync tokens (1/2: capture and commit)

airbyte_cdk/sources/declarative/declarative_component_schema.yaml

@@ -1428,6 +1428,68 @@ definitions:
       $parameters:
         type: object
         additionalProperties: true
+  OpaqueTokenCursor:
+    title: Opaque Token Cursor
+    description: >-
+      Incremental sync driven by an opaque change token that the API returns at the end of a
+      pagination pass, such as a sync token. The token is committed to state only after the
+      pass's records are emitted, and is sent back on the next sync. Tokens are never parsed,
+      compared or derived from records.
+    type: object
+    required: [type, token_path, token_option]
+    additionalProperties: true
+    properties:
+      type:
+        type: string
+        enum: [OpaqueTokenCursor]
+      token_path:
+        title: Token Path
+        description: >-
+          Path to the next token in the decoded response that ends a pagination pass. The
+          value must be a string or an integer, and is stored and sent as a string. A missing,
+          null or empty value means the response carried no token.
+        type: array
+        items:
+          type: string
+        interpolation_context: [config]
+        examples:
+          - ["syncToken"]
+          - ["nextSyncToken"]
+          - ["meta", "sync_token"]
+      token_option:
+        title: Send Token In
+        description: >-
+          Where to send the stored token on each request of a pass: the JSON body, the query
+          string, a header or the form body.
+        "$ref": "#/definitions/RequestOption"
+      completion_condition:
+        title: Completion Condition
+        description: >-
+          Must be true on the last response of a pass for its token to be committed. Defaults
+          to a token being present at token_path. Set it when the API repeats the old token on
+          intermediate pages or returns a position on every page.
+        type: string
+        interpolation_context: [config, headers, response, stream_partition, stream_slice]
+        examples:
+          - "{{ not response.moreDataAvailable }}"
+      initial_token:
+        title: Initial Token
+        description: >-
+          Value to send when no token is stored, for an API that needs one to start a full
+          pass, such as Todoist's "*". When unset, nothing is sent.
+        type: string
+        interpolation_context: [config]
+        examples: ["*"]
+      cursor_field:
+        title: Destination Cursor Field
+        description: >-
+          Optional top-level record field advertised as the stream's cursor, so destinations
+          can order versions of a record when deduplicating. It is never used to filter
+          records or to build state.
+        type: string
+      $parameters:
+        type: object
+        additionalProperties: true
   JwtAuthenticator:
     title: JWT Authenticator
     description: Authenticator for requests using JWT authentication flow.
@@ -1845,6 +1907,7 @@ definitions:
         anyOf:
           - "$ref": "#/definitions/DatetimeBasedCursor"
           - "$ref": "#/definitions/IncrementingCountCursor"
+          - "$ref": "#/definitions/OpaqueTokenCursor"
       primary_key:
         title: Primary Key
         "$ref": "#/definitions/PrimaryKey"

airbyte_cdk/sources/declarative/incremental/__init__.py

@@ -6,8 +6,10 @@
     ConcurrentCursorFactory,
     ConcurrentPerPartitionCursor,
 )
+from airbyte_cdk.sources.declarative.incremental.opaque_token_cursor import OpaqueTokenCursor
 
 __all__ = [
     "ConcurrentCursorFactory",
     "ConcurrentPerPartitionCursor",
+    "OpaqueTokenCursor",
 ]