memcode-sdk 2.4.0__tar.gz → 2.5.0__tar.gz

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memcode-sdk
-Version: 2.4.0
+Version: 2.5.0
 Summary: Python SDK for the Memcode long-term memory API
 Author: Memcode
 License-Expression: Apache-2.0
@@ -31,7 +31,7 @@ Available in Python, TypeScript, and Go.
 All three SDKs share the same design principles:
 
 - Existing v1 clients keep three 1:1 methods: **ingest**, **retrieve**, **search**
-- Bearer-token authentication via constructor arg or `MEMCODE_API_KEY` env var
+- Bearer-token authentication via a static key or refreshable token provider
 - Typed error hierarchy so callers can handle auth, rate-limit, and server errors distinctly
 - Zero config defaults — point at `localhost:8000` with no key and it just works in dev
 
@@ -233,9 +233,26 @@ registration = await oauth.register_client(
     client_name="My Pipecat agent",
     redirect_uris=["https://voice.example.com/oauth/callback"],
     application_type="web",
+    software_id="ai.pipecat.memcode",
+    software_version="1.0.0",
 )
 ```
 
+`software_id` is a stable public package identifier, not a credential. If it is
+registered by Memcode, loopback or otherwise unverified callbacks can be counted
+under that integration with `attribution_status="unverified"` and
+`attribution_basis="dcr_software_id"`. An exact registered HTTPS callback is
+still required for verified SDK attribution. Conflicting callback and software
+owners are rejected by the authorization server.
+
+Memcode may return read-only `integration_id`, `integration_channel`,
+`attribution_status`, and `attribution_basis` values on the registration.
+They are assigned by the server from its trusted integration registry. The SDK
+does not send these values during registration or on Memory API requests, so
+applications need no attribution parameter or additional attribution secret.
+Older servers may omit all four values. Tenant-bound v2 requests reject these
+server-owned field names when supplied in request metadata.
+
 The helper uses Authorization Code with S256 PKCE, resource indicators,
 rotating refresh tokens, and single-flight refresh per token-store key. A 401
 causes at most one refresh and one request retry.
@@ -378,6 +395,47 @@ const advancedAnswer = await client.retrieveV2({
 });
 ```
 
+### OAuth and dynamic bearer tokens
+
+TypeScript 2.5 adds `MemcodeOAuthClient`, `OAuthTokenStore`, and
+`DelegatingMemoryTokenProvider`. The flow uses dynamic client registration,
+Authorization Code with S256 PKCE, resource indicators, rotating refresh
+tokens, and revocation:
+
+```typescript
+import { MemcodeClient, MemcodeOAuthClient } from "memcode-sdk";
+
+const oauth = new MemcodeOAuthClient({
+  issuer: "https://memory.memcode.in/",
+  resource: "https://memory.memcode.in",
+  clientId: persistedDynamicClientId,
+  tokenKey: `voice:${applicationUserId}`,
+  tokenStore: encryptedDistributedTokenStore,
+});
+
+const request = await oauth.createAuthorizationRequest({
+  redirectUri: "https://voice.example.com/oauth/callback",
+});
+await oauth.exchangeCode({
+  code: callbackCode,
+  returnedState: callbackState,
+  authorizationRequest: request,
+});
+
+const oauthClient = new MemcodeClient("https://memory.memcode.in", oauth);
+```
+
+Dynamic-registration responses may expose the server-assigned, read-only
+`integrationId`, `integrationChannel`, `attributionStatus`, and
+`attributionBasis` fields. The SDK never sends those values in registration or
+Memory API requests; no integration-supplied attribution parameter or new
+secret is required. All fields remain optional for older servers, and the same
+server-owned names are rejected in tenant-bound v2 request metadata.
+
+The legacy function-style `MemcodeV2Client.accessTokenProvider` remains
+supported. A refreshable object provider gets at most one refresh and one
+request retry after a 401.
+
 ### Error handling
 
 ```typescript
@@ -515,6 +573,57 @@ func main() {
 }
 ```
 
+### OAuth and dynamic bearer tokens
+
+Go 2.4 adds `OAuthClient`, `OAuthTokenStore`, and
+`DelegatingMemoryTokenProvider`. OAuth operations take `context.Context`; the
+API clients resolve a token per request and perform at most one refresh and one
+retry after a 401.
+
+```go
+store := encryptedDistributedTokenStore
+oauth, err := memcode.NewOAuthClient(memcode.OAuthClientOptions{
+    Issuer:     "https://memory.memcode.in/",
+    Resource:   "https://memory.memcode.in",
+    ClientID:   persistedDynamicClientID,
+    TokenKey:   "voice:" + applicationUserID,
+    TokenStore: store,
+})
+if err != nil {
+    panic(err)
+}
+
+request, err := oauth.CreateAuthorizationRequest(ctx,
+    memcode.CreateAuthorizationRequestOptions{
+        RedirectURI: "https://voice.example.com/oauth/callback",
+    })
+// Redirect to request.AuthorizationURL and retain request server-side.
+tokens, err := oauth.ExchangeCode(ctx, callbackCode, callbackState, request)
+_ = tokens
+
+client, err := memcode.NewClientWithAccessTokenProvider(
+    "https://memory.memcode.in",
+    oauth,
+)
+```
+
+`RegisterOAuthClientOptions` also accepts `SoftwareID` and `SoftwareVersion`.
+`SoftwareID` is a public analytics identifier, not a credential; when it is the
+only registry match, the server returns unverified `dcr_software_id`
+attribution. An exact registered HTTPS callback is still required for verified
+SDK attribution.
+
+`OAuthClientRegistration` may contain read-only `IntegrationID`,
+`IntegrationChannel`, `AttributionStatus`, and `AttributionBasis` values
+assigned by the server. They are not DCR inputs and are never copied to Memory
+API requests, so callers need no attribution parameter or additional secret.
+The fields are empty when an older server omits them. Tenant-bound v2 ingest
+rejects the same server-owned names in request metadata.
+
+The supplied store must encrypt tokens, atomically replace rotated token sets,
+and implement `WithRefreshLease` as a distributed lease when multiple workers
+share a grant. `NewInMemoryOAuthTokenStore` is only for tests and examples.
+
 ### Error handling
 
 ```go

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/README.MD

@@ -8,7 +8,7 @@ Available in Python, TypeScript, and Go.
 All three SDKs share the same design principles:
 
 - Existing v1 clients keep three 1:1 methods: **ingest**, **retrieve**, **search**
-- Bearer-token authentication via constructor arg or `MEMCODE_API_KEY` env var
+- Bearer-token authentication via a static key or refreshable token provider
 - Typed error hierarchy so callers can handle auth, rate-limit, and server errors distinctly
 - Zero config defaults — point at `localhost:8000` with no key and it just works in dev
 
@@ -210,9 +210,26 @@ registration = await oauth.register_client(
     client_name="My Pipecat agent",
     redirect_uris=["https://voice.example.com/oauth/callback"],
     application_type="web",
+    software_id="ai.pipecat.memcode",
+    software_version="1.0.0",
 )
 ```
 
+`software_id` is a stable public package identifier, not a credential. If it is
+registered by Memcode, loopback or otherwise unverified callbacks can be counted
+under that integration with `attribution_status="unverified"` and
+`attribution_basis="dcr_software_id"`. An exact registered HTTPS callback is
+still required for verified SDK attribution. Conflicting callback and software
+owners are rejected by the authorization server.
+
+Memcode may return read-only `integration_id`, `integration_channel`,
+`attribution_status`, and `attribution_basis` values on the registration.
+They are assigned by the server from its trusted integration registry. The SDK
+does not send these values during registration or on Memory API requests, so
+applications need no attribution parameter or additional attribution secret.
+Older servers may omit all four values. Tenant-bound v2 requests reject these
+server-owned field names when supplied in request metadata.
+
 The helper uses Authorization Code with S256 PKCE, resource indicators,
 rotating refresh tokens, and single-flight refresh per token-store key. A 401
 causes at most one refresh and one request retry.
@@ -355,6 +372,47 @@ const advancedAnswer = await client.retrieveV2({
 });
 ```
 
+### OAuth and dynamic bearer tokens
+
+TypeScript 2.5 adds `MemcodeOAuthClient`, `OAuthTokenStore`, and
+`DelegatingMemoryTokenProvider`. The flow uses dynamic client registration,
+Authorization Code with S256 PKCE, resource indicators, rotating refresh
+tokens, and revocation:
+
+```typescript
+import { MemcodeClient, MemcodeOAuthClient } from "memcode-sdk";
+
+const oauth = new MemcodeOAuthClient({
+  issuer: "https://memory.memcode.in/",
+  resource: "https://memory.memcode.in",
+  clientId: persistedDynamicClientId,
+  tokenKey: `voice:${applicationUserId}`,
+  tokenStore: encryptedDistributedTokenStore,
+});
+
+const request = await oauth.createAuthorizationRequest({
+  redirectUri: "https://voice.example.com/oauth/callback",
+});
+await oauth.exchangeCode({
+  code: callbackCode,
+  returnedState: callbackState,
+  authorizationRequest: request,
+});
+
+const oauthClient = new MemcodeClient("https://memory.memcode.in", oauth);
+```
+
+Dynamic-registration responses may expose the server-assigned, read-only
+`integrationId`, `integrationChannel`, `attributionStatus`, and
+`attributionBasis` fields. The SDK never sends those values in registration or
+Memory API requests; no integration-supplied attribution parameter or new
+secret is required. All fields remain optional for older servers, and the same
+server-owned names are rejected in tenant-bound v2 request metadata.
+
+The legacy function-style `MemcodeV2Client.accessTokenProvider` remains
+supported. A refreshable object provider gets at most one refresh and one
+request retry after a 401.
+
 ### Error handling
 
 ```typescript
@@ -492,6 +550,57 @@ func main() {
 }
 ```
 
+### OAuth and dynamic bearer tokens
+
+Go 2.4 adds `OAuthClient`, `OAuthTokenStore`, and
+`DelegatingMemoryTokenProvider`. OAuth operations take `context.Context`; the
+API clients resolve a token per request and perform at most one refresh and one
+retry after a 401.
+
+```go
+store := encryptedDistributedTokenStore
+oauth, err := memcode.NewOAuthClient(memcode.OAuthClientOptions{
+    Issuer:     "https://memory.memcode.in/",
+    Resource:   "https://memory.memcode.in",
+    ClientID:   persistedDynamicClientID,
+    TokenKey:   "voice:" + applicationUserID,
+    TokenStore: store,
+})
+if err != nil {
+    panic(err)
+}
+
+request, err := oauth.CreateAuthorizationRequest(ctx,
+    memcode.CreateAuthorizationRequestOptions{
+        RedirectURI: "https://voice.example.com/oauth/callback",
+    })
+// Redirect to request.AuthorizationURL and retain request server-side.
+tokens, err := oauth.ExchangeCode(ctx, callbackCode, callbackState, request)
+_ = tokens
+
+client, err := memcode.NewClientWithAccessTokenProvider(
+    "https://memory.memcode.in",
+    oauth,
+)
+```
+
+`RegisterOAuthClientOptions` also accepts `SoftwareID` and `SoftwareVersion`.
+`SoftwareID` is a public analytics identifier, not a credential; when it is the
+only registry match, the server returns unverified `dcr_software_id`
+attribution. An exact registered HTTPS callback is still required for verified
+SDK attribution.
+
+`OAuthClientRegistration` may contain read-only `IntegrationID`,
+`IntegrationChannel`, `AttributionStatus`, and `AttributionBasis` values
+assigned by the server. They are not DCR inputs and are never copied to Memory
+API requests, so callers need no attribution parameter or additional secret.
+The fields are empty when an older server omits them. Tenant-bound v2 ingest
+rejects the same server-owned names in request metadata.
+
+The supplied store must encrypt tokens, atomically replace rotated token sets,
+and implement `WithRefreshLease` as a distributed lease when multiple workers
+share a grant. `NewInMemoryOAuthTokenStore` is only for tests and examples.
+
 ### Error handling
 
 ```go

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/memcode_sdk/__init__.py

@@ -79,7 +79,7 @@ from .v2_types import (
 )
 
 __author__ = "Memcode Team"
-__version__ = "2.4.0"
+__version__ = "2.5.0"
 __license__ = "Apache-2.0"
 
 __all__ = [

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/memcode_sdk/async_v2_client.py

@@ -18,6 +18,7 @@ from .v2_client import (
     _parse_search,
     _required,
     _result_mode,
+    _safe_request_metadata,
     _scope,
     _search_mode,
     _top_k,
@@ -82,7 +83,7 @@ class AsyncMemcodeV2Client:
             if value is not None:
                 payload[name] = _required(name, value)
         if metadata is not None:
-            payload["metadata"] = metadata
+            payload["metadata"] = _safe_request_metadata(metadata)
         if tags is not None:
             payload["tags"] = list(dict.fromkeys(_required("tag", tag) for tag in tags))
         env = await self._transport.post(

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/memcode_sdk/oauth.py

@@ -42,11 +42,10 @@ from .errors import OAuthError
 
 DEFAULT_ISSUER = "https://memory.memcode.in/"
 DEFAULT_MEMORY_RESOURCE = "https://memory.memcode.in"
-DEFAULT_MCP_DELEGATE_ENDPOINT = (
-    "https://memory.memcode.in/auth/mcp/oauth/delegate"
-)
+DEFAULT_MCP_DELEGATE_ENDPOINT = "https://memory.memcode.in/auth/mcp/oauth/delegate"
 DEFAULT_SCOPES = ("memory:read", "memory:write")
 _PKCE_VERIFIER_RE = re.compile(r"^[A-Za-z0-9._~-]{43,128}$")
+_SOFTWARE_ID_RE = re.compile(r"^[a-z][a-z0-9_.-]{0,127}$")
 
 
 @runtime_checkable
@@ -168,7 +167,15 @@ class OAuthClientRegistration:
     client_name: Optional[str] = None
     redirect_uris: Tuple[str, ...] = ()
     scope: Tuple[str, ...] = ()
+    software_id: Optional[str] = None
+    software_version: Optional[str] = None
     raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+    # Read-only server attribution. These values are never accepted as DCR
+    # inputs and may be absent on older Memcode deployments.
+    integration_id: Optional[str] = None
+    integration_channel: Optional[str] = None
+    attribution_status: Optional[str] = None
+    attribution_basis: Optional[str] = None
 
 
 @dataclass(frozen=True)
@@ -187,7 +194,9 @@ class PKCEAuthorizationRequest:
 def _normalize_scopes(scopes: Sequence[str]) -> Tuple[str, ...]:
     if isinstance(scopes, (str, bytes)):
         raise TypeError("OAuth scopes must be a sequence of scope strings")
-    normalized = tuple(dict.fromkeys(scope.strip() for scope in scopes if scope.strip()))
+    normalized = tuple(
+        dict.fromkeys(scope.strip() for scope in scopes if scope.strip())
+    )
     if not normalized:
         raise ValueError("At least one OAuth scope is required")
     return normalized
@@ -225,7 +234,9 @@ def _oauth_error_from_response(response: httpx.Response) -> OAuthError:
         payload = {}
     error = payload.get("error")
     description = payload.get("error_description") or payload.get("detail")
-    message = str(description or error or f"OAuth request failed with HTTP {response.status_code}")
+    message = str(
+        description or error or f"OAuth request failed with HTTP {response.status_code}"
+    )
     return OAuthError(
         message,
         error=str(error) if error else None,
@@ -296,9 +307,7 @@ class AsyncMemcodeOAuthClient(AsyncAccessTokenProvider):
         self._refresh_task_guard = asyncio.Lock()
         self._refresh_task: Optional[asyncio.Task[str]] = None
         self._registration_task_guard = asyncio.Lock()
-        self._registration_task: Optional[
-            asyncio.Task[OAuthClientRegistration]
-        ] = None
+        self._registration_task: Optional[asyncio.Task[OAuthClientRegistration]] = None
         self._registration_fingerprint: Optional[Tuple[Any, ...]] = None
         self._client_registration: Optional[OAuthClientRegistration] = None
         self._lifecycle_tasks: "set[asyncio.Task[Any]]" = set()
@@ -443,24 +452,43 @@ class AsyncMemcodeOAuthClient(AsyncAccessTokenProvider):
         client_name: str = "Memcode Python client",
         application_type: str = "web",
         scopes: Optional[Sequence[str]] = None,
+        software_id: Optional[str] = None,
+        software_version: Optional[str] = None,
     ) -> OAuthClientRegistration:
-        """Dynamically register a public Authorization Code client."""
+        """Dynamically register a public Authorization Code client.
+
+        ``software_id`` is a public package identifier, not a secret or proof
+        of authenticity. Memcode may use a registered value for unverified
+        integration analytics while keeping attribution server-owned.
+        """
         metadata = await self.discover()
         if not metadata.registration_endpoint:
             raise OAuthError("Authorization server does not advertise DCR")
         if isinstance(redirect_uris, (str, bytes)):
             raise TypeError("redirect_uris must be a sequence of URI strings")
-        normalized_redirects = tuple(dict.fromkeys(uri.strip() for uri in redirect_uris))
+        normalized_redirects = tuple(
+            dict.fromkeys(uri.strip() for uri in redirect_uris)
+        )
         if not normalized_redirects or any(not uri for uri in normalized_redirects):
             raise ValueError("At least one non-empty redirect URI is required")
         if application_type not in {"native", "web"}:
             raise ValueError("application_type must be native or web")
+        normalized_software_id = (software_id or "").strip().lower() or None
+        if normalized_software_id and not _SOFTWARE_ID_RE.fullmatch(
+            normalized_software_id
+        ):
+            raise ValueError("software_id must be a canonical public identifier")
+        normalized_software_version = (software_version or "").strip() or None
+        if normalized_software_version and len(normalized_software_version) > 64:
+            raise ValueError("software_version cannot exceed 64 characters")
         requested_scopes = _normalize_scopes(scopes or self.scopes)
         fingerprint: Tuple[Any, ...] = (
             tuple(sorted(normalized_redirects)),
             client_name,
             application_type,
             tuple(sorted(requested_scopes)),
+            normalized_software_id,
+            normalized_software_version,
         )
         async with self._registration_task_guard:
             if (
@@ -482,6 +510,8 @@ class AsyncMemcodeOAuthClient(AsyncAccessTokenProvider):
                         client_name=client_name,
                         application_type=application_type,
                         requested_scopes=requested_scopes,
+                        software_id=normalized_software_id,
+                        software_version=normalized_software_version,
                         fingerprint=fingerprint,
                     ),
                     name="memcode-oauth-client-registration",
@@ -498,20 +528,27 @@ class AsyncMemcodeOAuthClient(AsyncAccessTokenProvider):
         client_name: str,
         application_type: str,
         requested_scopes: Tuple[str, ...],
+        software_id: Optional[str],
+        software_version: Optional[str],
         fingerprint: Tuple[Any, ...],
     ) -> OAuthClientRegistration:
+        registration_payload: Dict[str, Any] = {
+            "client_name": client_name,
+            "redirect_uris": list(redirect_uris),
+            "token_endpoint_auth_method": "none",
+            "grant_types": ["authorization_code", "refresh_token"],
+            "response_types": ["code"],
+            "scope": " ".join(requested_scopes),
+            "application_type": application_type,
+        }
+        if software_id:
+            registration_payload["software_id"] = software_id
+        if software_version:
+            registration_payload["software_version"] = software_version
         payload = await self._request_json(
             "POST",
             registration_endpoint,
-            json={
-                "client_name": client_name,
-                "redirect_uris": list(redirect_uris),
-                "token_endpoint_auth_method": "none",
-                "grant_types": ["authorization_code", "refresh_token"],
-                "response_types": ["code"],
-                "scope": " ".join(requested_scopes),
-                "application_type": application_type,
-            },
+            json=registration_payload,
         )
         client_id = str(payload.get("client_id") or "")
         if not client_id:
@@ -526,10 +563,37 @@ class AsyncMemcodeOAuthClient(AsyncAccessTokenProvider):
             client_name=(
                 str(payload["client_name"]) if payload.get("client_name") else None
             ),
-            redirect_uris=tuple(payload.get("redirect_uris") or normalized_redirects),
-            scope=(
-                tuple(str(payload.get("scope") or "").split())
-                or requested_scopes
+            redirect_uris=tuple(payload.get("redirect_uris") or redirect_uris),
+            scope=(tuple(str(payload.get("scope") or "").split()) or requested_scopes),
+            software_id=(
+                str(payload["software_id"])
+                if payload.get("software_id") is not None
+                else software_id
+            ),
+            software_version=(
+                str(payload["software_version"])
+                if payload.get("software_version") is not None
+                else software_version
+            ),
+            integration_id=(
+                str(payload["integration_id"])
+                if payload.get("integration_id") is not None
+                else None
+            ),
+            integration_channel=(
+                str(payload["integration_channel"])
+                if payload.get("integration_channel") is not None
+                else None
+            ),
+            attribution_status=(
+                str(payload["attribution_status"])
+                if payload.get("attribution_status") is not None
+                else None
+            ),
+            attribution_basis=(
+                str(payload["attribution_basis"])
+                if payload.get("attribution_basis") is not None
+                else None
             ),
             raw=dict(payload),
         )
@@ -654,11 +718,7 @@ class AsyncMemcodeOAuthClient(AsyncAccessTokenProvider):
         if token_type.lower() != "bearer":
             raise OAuthError("Memcode requires Bearer access tokens")
         raw_scope = payload.get("scope")
-        scopes = (
-            tuple(str(raw_scope).split())
-            if raw_scope
-            else tuple(fallback_scope)
-        )
+        scopes = tuple(str(raw_scope).split()) if raw_scope else tuple(fallback_scope)
         resource = str(payload.get("resource") or self.resource)
         if resource.rstrip("/") != self.resource.rstrip("/"):
             raise OAuthError("Token response resource mismatch")

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/memcode_sdk/v2_client.py

@@ -27,6 +27,12 @@ from .v2_types import (
 _READ_SCOPES = {"inherited", "context_only"}
 _SEARCH_MODES = {"default", "global"}
 _RESULT_MODES = {"default", "chunks", "memories"}
+_RESERVED_ATTRIBUTION_METADATA = {
+    "integration_id",
+    "integration_channel",
+    "attribution_status",
+    "attribution_basis",
+}
 
 
 def _required(name: str, value: str) -> str:
@@ -75,6 +81,16 @@ def _result_mode(value: SearchResultMode) -> SearchResultMode:
     return value
 
 
+def _safe_request_metadata(metadata: Dict[str, Any]) -> Dict[str, Any]:
+    reserved = _RESERVED_ATTRIBUTION_METADATA.intersection(metadata)
+    if reserved:
+        fields = ", ".join(sorted(reserved))
+        raise ValueError(
+            f"MemcodeV2Client: metadata fields are server-reserved: {fields}"
+        )
+    return metadata
+
+
 def _metadata(data: Dict[str, Any], request_id: Optional[str], elapsed_ms: Optional[float]) -> Dict[str, Any]:
     return {**data, "request_id": request_id, "elapsed_ms": elapsed_ms}
 
@@ -214,7 +230,7 @@ class MemcodeV2Client:
             if value is not None:
                 payload[name] = _required(name, value)
         if metadata is not None:
-            payload["metadata"] = metadata
+            payload["metadata"] = _safe_request_metadata(metadata)
         if tags is not None:
             payload["tags"] = list(dict.fromkeys(_required("tag", tag) for tag in tags))
         env = self._transport.post(

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/memcode_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memcode-sdk
-Version: 2.4.0
+Version: 2.5.0
 Summary: Python SDK for the Memcode long-term memory API
 Author: Memcode
 License-Expression: Apache-2.0
@@ -31,7 +31,7 @@ Available in Python, TypeScript, and Go.
 All three SDKs share the same design principles:
 
 - Existing v1 clients keep three 1:1 methods: **ingest**, **retrieve**, **search**
-- Bearer-token authentication via constructor arg or `MEMCODE_API_KEY` env var
+- Bearer-token authentication via a static key or refreshable token provider
 - Typed error hierarchy so callers can handle auth, rate-limit, and server errors distinctly
 - Zero config defaults — point at `localhost:8000` with no key and it just works in dev
 
@@ -233,9 +233,26 @@ registration = await oauth.register_client(
     client_name="My Pipecat agent",
     redirect_uris=["https://voice.example.com/oauth/callback"],
     application_type="web",
+    software_id="ai.pipecat.memcode",
+    software_version="1.0.0",
 )
 ```
 
+`software_id` is a stable public package identifier, not a credential. If it is
+registered by Memcode, loopback or otherwise unverified callbacks can be counted
+under that integration with `attribution_status="unverified"` and
+`attribution_basis="dcr_software_id"`. An exact registered HTTPS callback is
+still required for verified SDK attribution. Conflicting callback and software
+owners are rejected by the authorization server.
+
+Memcode may return read-only `integration_id`, `integration_channel`,
+`attribution_status`, and `attribution_basis` values on the registration.
+They are assigned by the server from its trusted integration registry. The SDK
+does not send these values during registration or on Memory API requests, so
+applications need no attribution parameter or additional attribution secret.
+Older servers may omit all four values. Tenant-bound v2 requests reject these
+server-owned field names when supplied in request metadata.
+
 The helper uses Authorization Code with S256 PKCE, resource indicators,
 rotating refresh tokens, and single-flight refresh per token-store key. A 401
 causes at most one refresh and one request retry.
@@ -378,6 +395,47 @@ const advancedAnswer = await client.retrieveV2({
 });
 ```
 
+### OAuth and dynamic bearer tokens
+
+TypeScript 2.5 adds `MemcodeOAuthClient`, `OAuthTokenStore`, and
+`DelegatingMemoryTokenProvider`. The flow uses dynamic client registration,
+Authorization Code with S256 PKCE, resource indicators, rotating refresh
+tokens, and revocation:
+
+```typescript
+import { MemcodeClient, MemcodeOAuthClient } from "memcode-sdk";
+
+const oauth = new MemcodeOAuthClient({
+  issuer: "https://memory.memcode.in/",
+  resource: "https://memory.memcode.in",
+  clientId: persistedDynamicClientId,
+  tokenKey: `voice:${applicationUserId}`,
+  tokenStore: encryptedDistributedTokenStore,
+});
+
+const request = await oauth.createAuthorizationRequest({
+  redirectUri: "https://voice.example.com/oauth/callback",
+});
+await oauth.exchangeCode({
+  code: callbackCode,
+  returnedState: callbackState,
+  authorizationRequest: request,
+});
+
+const oauthClient = new MemcodeClient("https://memory.memcode.in", oauth);
+```
+
+Dynamic-registration responses may expose the server-assigned, read-only
+`integrationId`, `integrationChannel`, `attributionStatus`, and
+`attributionBasis` fields. The SDK never sends those values in registration or
+Memory API requests; no integration-supplied attribution parameter or new
+secret is required. All fields remain optional for older servers, and the same
+server-owned names are rejected in tenant-bound v2 request metadata.
+
+The legacy function-style `MemcodeV2Client.accessTokenProvider` remains
+supported. A refreshable object provider gets at most one refresh and one
+request retry after a 401.
+
 ### Error handling
 
 ```typescript
@@ -515,6 +573,57 @@ func main() {
 }
 ```
 
+### OAuth and dynamic bearer tokens
+
+Go 2.4 adds `OAuthClient`, `OAuthTokenStore`, and
+`DelegatingMemoryTokenProvider`. OAuth operations take `context.Context`; the
+API clients resolve a token per request and perform at most one refresh and one
+retry after a 401.
+
+```go
+store := encryptedDistributedTokenStore
+oauth, err := memcode.NewOAuthClient(memcode.OAuthClientOptions{
+    Issuer:     "https://memory.memcode.in/",
+    Resource:   "https://memory.memcode.in",
+    ClientID:   persistedDynamicClientID,
+    TokenKey:   "voice:" + applicationUserID,
+    TokenStore: store,
+})
+if err != nil {
+    panic(err)
+}
+
+request, err := oauth.CreateAuthorizationRequest(ctx,
+    memcode.CreateAuthorizationRequestOptions{
+        RedirectURI: "https://voice.example.com/oauth/callback",
+    })
+// Redirect to request.AuthorizationURL and retain request server-side.
+tokens, err := oauth.ExchangeCode(ctx, callbackCode, callbackState, request)
+_ = tokens
+
+client, err := memcode.NewClientWithAccessTokenProvider(
+    "https://memory.memcode.in",
+    oauth,
+)
+```
+
+`RegisterOAuthClientOptions` also accepts `SoftwareID` and `SoftwareVersion`.
+`SoftwareID` is a public analytics identifier, not a credential; when it is the
+only registry match, the server returns unverified `dcr_software_id`
+attribution. An exact registered HTTPS callback is still required for verified
+SDK attribution.
+
+`OAuthClientRegistration` may contain read-only `IntegrationID`,
+`IntegrationChannel`, `AttributionStatus`, and `AttributionBasis` values
+assigned by the server. They are not DCR inputs and are never copied to Memory
+API requests, so callers need no attribution parameter or additional secret.
+The fields are empty when an older server omits them. Tenant-bound v2 ingest
+rejects the same server-owned names in request metadata.
+
+The supplied store must encrypt tokens, atomically replace rotated token sets,
+and implement `WithRefreshLease` as a distributed lease when multiple workers
+share a grant. `NewInMemoryOAuthTokenStore` is only for tests and examples.
+
 ### Error handling
 
 ```go

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memcode-sdk"
-version = "2.4.0"
+version = "2.5.0"
 description = "Python SDK for the Memcode long-term memory API"
 readme = { file = "README.MD", content-type = "text/markdown" }
 requires-python = ">=3.9"

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/tests/test_oauth.py

@@ -74,9 +74,11 @@ class AsyncTransportAuthTests(unittest.IsolatedAsyncioTestCase):
     async def test_provider_is_resolved_per_request_and_retries_one_401(self):
         provider = FakeTokenProvider()
         authorizations = []
+        request_headers = []
 
         async def handler(request):
             authorizations.append(request.headers.get("Authorization"))
+            request_headers.append({name.lower() for name in request.headers})
             if len(authorizations) == 1:
                 return httpx.Response(401, json={"error": "expired"})
             return httpx.Response(200, json=envelope({"results": [], "total": 0}))
@@ -103,6 +105,10 @@ class AsyncTransportAuthTests(unittest.IsolatedAsyncioTestCase):
         )
         self.assertEqual(provider.get_calls, 2)
         self.assertEqual(provider.refresh_calls, 1)
+        self.assertTrue(all(
+            not any("integration" in name or "attribution" in name for name in headers)
+            for headers in request_headers
+        ))
 
     async def test_second_401_is_returned_without_a_third_attempt(self):
         provider = FakeTokenProvider()
@@ -281,6 +287,10 @@ class OAuthLifecycleCancellationTests(unittest.IsolatedAsyncioTestCase):
             allow_registration_response.set()
             registration = await asyncio.wait_for(retry, timeout=1)
             self.assertEqual(registration.client_id, "client-recovered")
+            self.assertIsNone(registration.integration_id)
+            self.assertIsNone(registration.integration_channel)
+            self.assertIsNone(registration.attribution_status)
+            self.assertIsNone(registration.attribution_basis)
             self.assertEqual(oauth.client_id, "client-recovered")
             cached = await oauth.register_client(
                 client_name="Pipecat Memcode",
@@ -326,6 +336,10 @@ class OAuthClientTests(unittest.IsolatedAsyncioTestCase):
                 return httpx.Response(201, json={
                     "client_id": "client-1",
                     "client_id_issued_at": 1_700_000_000,
+                    "integration_id": "voice_partner",
+                    "integration_channel": "sdk",
+                    "attribution_status": "verified",
+                    "attribution_basis": "verified_redirect",
                     **body,
                 })
             if request.url.path == "/oauth/token":
@@ -375,6 +389,45 @@ class OAuthClientTests(unittest.IsolatedAsyncioTestCase):
         await self.oauth.close()
         await self.http.aclose()
 
+    async def test_dcr_attribution_response_fields_are_optional(self):
+        async def handler(request):
+            if request.url.path == "/.well-known/oauth-authorization-server":
+                return httpx.Response(200, json={
+                    "issuer": "https://memory.example.com/",
+                    "authorization_endpoint": "https://app.example.com/oauth/authorize",
+                    "token_endpoint": "https://memory.example.com/oauth/token",
+                    "registration_endpoint": "https://memory.example.com/oauth/register",
+                    "code_challenge_methods_supported": ["S256"],
+                })
+            if request.url.path == "/oauth/register":
+                return httpx.Response(201, json={"client_id": "legacy-client"})
+            return httpx.Response(404)
+
+        http = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+        oauth = AsyncMemcodeOAuthClient(
+            issuer="https://memory.example.com/",
+            resource="https://memory.example.com",
+            token_key="legacy-registration",
+            http_client=http,
+        )
+        try:
+            registration = await oauth.register_client(
+                redirect_uris=("https://voice.example.com/oauth/callback",),
+            )
+        finally:
+            await oauth.close()
+            await http.aclose()
+
+        self.assertEqual(registration.client_id, "legacy-client")
+        self.assertEqual(
+            registration.redirect_uris,
+            ("https://voice.example.com/oauth/callback",),
+        )
+        self.assertIsNone(registration.integration_id)
+        self.assertIsNone(registration.integration_channel)
+        self.assertIsNone(registration.attribution_status)
+        self.assertIsNone(registration.attribution_basis)
+
     async def test_dcr_pkce_exchange_singleflight_refresh_and_revocation(self):
         resource_metadata = await self.oauth.discover_protected_resource()
         self.assertEqual(
@@ -385,8 +438,36 @@ class OAuthClientTests(unittest.IsolatedAsyncioTestCase):
         registration = await self.oauth.register_client(
             client_name="Pipecat Memcode",
             redirect_uris=("https://voice.example.com/oauth/callback",),
+            software_id="ai.pipecat.memcode",
+            software_version="1.2.3",
         )
         self.assertEqual(registration.client_id, "client-1")
+        self.assertEqual(registration.software_id, "ai.pipecat.memcode")
+        self.assertEqual(registration.software_version, "1.2.3")
+        self.assertEqual(registration.integration_id, "voice_partner")
+        self.assertEqual(registration.integration_channel, "sdk")
+        self.assertEqual(registration.attribution_status, "verified")
+        self.assertEqual(registration.attribution_basis, "verified_redirect")
+
+        registration_request = next(
+            request for request in self.requests
+            if request.url.path == "/oauth/register"
+        )
+        registration_payload = json.loads(registration_request.content)
+        self.assertEqual(registration_payload["software_id"], "ai.pipecat.memcode")
+        self.assertEqual(registration_payload["software_version"], "1.2.3")
+        self.assertFalse({
+            "integration_id",
+            "integration_channel",
+            "attribution_status",
+            "attribution_basis",
+        } & registration_payload.keys())
+
+        with self.assertRaisesRegex(ValueError, "canonical public identifier"):
+            await self.oauth.register_client(
+                redirect_uris=("https://voice.example.com/oauth/callback",),
+                software_id="Attacker supplied identity",
+            )
 
         self.authorization = await self.oauth.create_authorization_request(
             redirect_uri="https://voice.example.com/oauth/callback",

{memcode_sdk-2.4.0 → memcode_sdk-2.5.0}/tests/test_v2_clients.py

@@ -114,6 +114,24 @@ class V2ClientTests(unittest.TestCase):
         self.assertNotIn("user_id", body)
         self.assertEqual(result.status, "processing")
 
+    def test_ingest_rejects_server_attribution_metadata(self):
+        for field in (
+            "integration_id",
+            "integration_channel",
+            "attribution_status",
+            "attribution_basis",
+        ):
+            with self.subTest(field=field):
+                before = len(self.requests)
+                with self.assertRaisesRegex(ValueError, "server-reserved"):
+                    self.client.ingest(
+                        space_id="space-1",
+                        content="Launch is Friday",
+                        idempotency_key=f"turn-{field}",
+                        metadata={field: "spoofed"},
+                    )
+                self.assertEqual(len(self.requests), before)
+
     def test_search_preserves_scope_mode_and_partial_metadata(self):
         result = self.client.search(
             context_space_id="space-1",
@@ -196,6 +214,35 @@ class V2ClientTests(unittest.TestCase):
 
 
 class AsyncV2ClientTests(unittest.IsolatedAsyncioTestCase):
+    async def test_async_ingest_rejects_server_attribution_metadata(self):
+        request_count = 0
+
+        async def handler(_request: httpx.Request) -> httpx.Response:
+            nonlocal request_count
+            request_count += 1
+            return httpx.Response(500)
+
+        client = AsyncMemcodeV2Client(
+            api_url="https://memory.example.com", api_key="secret",
+        )
+        await client._transport._client.aclose()
+        client._transport._client = httpx.AsyncClient(
+            base_url="https://memory.example.com",
+            transport=httpx.MockTransport(handler),
+        )
+        try:
+            with self.assertRaisesRegex(ValueError, "server-reserved"):
+                await client.ingest(
+                    space_id="space-1",
+                    content="Launch is Friday",
+                    idempotency_key="turn-1",
+                    metadata={"integration_id": "spoofed"},
+                )
+        finally:
+            await client.close()
+
+        self.assertEqual(request_count, 0)
+
     async def test_async_memory_graph_supports_nodes_only_page(self):
         captured = {}