From 58115add53869bb3a90997df46622b90f93c5ca1 Mon Sep 17 00:00:00 2001
From: Dominic Bosco <dominic@catenalabs.com>
Date: Tue, 29 Jul 2025 15:08:58 -0400
Subject: [PATCH] Improve did uri typing

---
 .changeset/big-suits-hammer.md      | 9 +++++++++
 packages/did/src/methods/did-key.ts | 3 ++-
 packages/did/src/methods/did-pkh.ts | 8 ++++----
 packages/did/src/methods/did-web.ts | 7 ++++---
 packages/did/src/types.ts           | 4 ++--
 5 files changed, 21 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/big-suits-hammer.md

diff --git a/.changeset/big-suits-hammer.md b/.changeset/big-suits-hammer.md
new file mode 100644
index 0000000..07905fa
--- /dev/null
+++ b/.changeset/big-suits-hammer.md
@@ -0,0 +1,9 @@
+---
+"@agentcommercekit/did": patch
+"@agentcommercekit/ack-id": patch
+"@agentcommercekit/ack-pay": patch
+"agentcommercekit": patch
+"@agentcommercekit/vc": patch
+---
+
+Scope return type of did pkh creation; improve did uri typing
diff --git a/packages/did/src/methods/did-key.ts b/packages/did/src/methods/did-key.ts
index 065778c..2233399 100644
--- a/packages/did/src/methods/did-key.ts
+++ b/packages/did/src/methods/did-key.ts
@@ -1,6 +1,7 @@
 import { getPublicKeyFromPrivateKey } from "@agentcommercekit/keys"
 import { bytesToMultibase } from "@agentcommercekit/keys/encoding"
 import * as varint from "varint"
+import type { DidUri } from "../did-uri"
 import type { Keypair } from "@agentcommercekit/keys"
 
 /**
@@ -15,7 +16,7 @@ import type { Keypair } from "@agentcommercekit/keys"
 /**
  * The `did:key` Uri type
  */
-export type DidKeyUri = `did:key:z${string}`
+export type DidKeyUri = DidUri<"key", `z${string}`>
 
 export const KEY_CONFIG = {
   secp256k1: {
diff --git a/packages/did/src/methods/did-pkh.ts b/packages/did/src/methods/did-pkh.ts
index 4df1d4e..5cee8d9 100644
--- a/packages/did/src/methods/did-pkh.ts
+++ b/packages/did/src/methods/did-pkh.ts
@@ -138,7 +138,7 @@ export function createBlockchainAccountId(
 export function createDidPkhUri(
   chainId: Caip2ChainId,
   address: string
-): DidUri {
+): DidPkhUri {
   return `did:pkh:${createCaip10AccountId(chainId, address)}`
 }
 
@@ -147,7 +147,7 @@ export function createDidPkhUri(
  */
 export function createDidPkhUriFromCaip10AccountId(
   caip10AccountId: Caip10AccountId
-): DidUri {
+): DidPkhUri {
   return `did:pkh:${caip10AccountId}`
 }
 
@@ -203,7 +203,7 @@ export function createDidPkhDocumentFromDidPkhUri(
 export function createDidPkhDocumentFromCaip10AccountId(
   caip10AccountId: Caip10AccountId,
   controller?: DidUri
-): DidUriWithDocument {
+): DidUriWithDocument<DidPkhUri> {
   const did = createDidPkhUriFromCaip10AccountId(caip10AccountId)
   const verificationMethod = createVerificationMethod(did, caip10AccountId)
   const additionalContexts = jsonLdContexts[verificationMethod.type]
@@ -234,7 +234,7 @@ export function createDidPkhDocument({
   address,
   chainId,
   controller
-}: CreateDidPkhDocumentOptions): DidUriWithDocument {
+}: CreateDidPkhDocumentOptions): DidUriWithDocument<DidPkhUri> {
   const caip10AccountId = createCaip10AccountId(chainId, address)
   return createDidPkhDocumentFromCaip10AccountId(caip10AccountId, controller)
 }
diff --git a/packages/did/src/methods/did-web.ts b/packages/did/src/methods/did-web.ts
index 42e8032..76e8d3e 100644
--- a/packages/did/src/methods/did-web.ts
+++ b/packages/did/src/methods/did-web.ts
@@ -6,12 +6,13 @@ import type {
   CreateDidDocumentFromKeypairOptions,
   CreateDidDocumentOptions
 } from "../create-did-document"
+import type { DidUri } from "../did-uri"
 import type { DidUriWithDocument } from "../types"
 
 /**
  * The type of a local Did
  */
-export type DidWebUri = `did:web:${string}`
+export type DidWebUri = DidUri<"web">
 
 // Utility type to distribute Omit over unions
 type DistributiveOmit<T, K extends keyof T> = T extends unknown
@@ -62,7 +63,7 @@ type CreateDidWebDocumentParams = {
 export function createDidWebDocument({
   baseUrl,
   ...options
-}: CreateDidWebDocumentParams): DidUriWithDocument {
+}: CreateDidWebDocumentParams): DidUriWithDocument<DidWebUri> {
   const did = createDidWebUri(baseUrl)
   const didDocument = createDidDocument({
     did,
@@ -91,7 +92,7 @@ type CreateDidWebDocumentFromKeypairParams = Omit<
 export function createDidWebDocumentFromKeypair({
   baseUrl,
   ...options
-}: CreateDidWebDocumentFromKeypairParams): DidUriWithDocument {
+}: CreateDidWebDocumentFromKeypairParams): DidUriWithDocument<DidWebUri> {
   const did = createDidWebUri(baseUrl)
   const didDocument = createDidDocumentFromKeypair({
     did,
diff --git a/packages/did/src/types.ts b/packages/did/src/types.ts
index f6a9217..69ff5da 100644
--- a/packages/did/src/types.ts
+++ b/packages/did/src/types.ts
@@ -1,7 +1,7 @@
 import type { DidDocument } from "./did-document"
 import type { DidUri } from "./did-uri"
 
-export interface DidUriWithDocument {
-  did: DidUri
+export interface DidUriWithDocument<T extends DidUri = DidUri> {
+  did: T
   didDocument: DidDocument
 }