Class Agent

Agent

Usage:

import { Agent } from '@web3-storage/access/agent'

Hierarchy

Agent

Index

Constructors

constructor

new Agent(data: AgentData, options?: AgentOptions): Agent
Parameters
- data: AgentData
  
  Agent data
- Optional options: AgentOptions
Returns Agent
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:53

Properties

`Private` #private

#private: any

connection

connection: ConnectionView<Service>

url

url: URL

Accessors

issuer

get issuer(): Signer<`did:${string}:${string}`, SigAlg>
Returns Signer<`did:${string}:${string}`, SigAlg>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:56

spaces

get spaces(): Map<`did:${string}:${string}`, SpaceMeta>
Returns Map<`did:${string}:${string}`, SpaceMeta>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:58

Methods

addProof

addProof(delegation: Delegation<Capabilities>): Promise<void>
Add a proof to the agent store

A proof is a delegation with an audience matching agent DID
Parameters
- delegation: Delegation<Capabilities>
Returns Promise<void>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:67

createSpace

createSpace(name?: string): Promise<{
    did: `did:key:${string}`;
    meta: SpaceMeta;
    proof: Delegation<[ToDeriveClaim<{
        can: "*";
        nb?: InferCaveats<{}>;
        with: URI<"did:">;
    }>]>;
}>
Creates a space signer and a delegation to the agent
Parameters
- Optional name: string
Returns Promise<{
    did: `did:key:${string}`;
    meta: SpaceMeta;
    proof: Delegation<[ToDeriveClaim<{
        can: "*";
        nb?: InferCaveats<{}>;
        with: URI<"did:">;
    }>]>;
}>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:100

currentSpace

currentSpace(): undefined | `did:${string}:${string}`
Get current space DID

Returns undefined | `did:${string}:${string}`
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:147

currentSpaceWithMeta

currentSpaceWithMeta(): undefined | {
    capabilities: any[];
    did: `did:${string}:${string}`;
    meta: undefined | SpaceMeta;
    proofs: Delegation<Capabilities>[];
}
Get current space DID, proofs and abilities

Returns undefined | {
    capabilities: any[];
    did: `did:${string}:${string}`;
    meta: undefined | SpaceMeta;
    proofs: Delegation<Capabilities>[];
}
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:151

delegate

delegate(options: DelegationOptions): Promise<Delegation<Capabilities>>
Parameters
- options: DelegationOptions
Returns Promise<Delegation<Capabilities>>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:173

delegations

delegations(caps?: Capability<Ability, `${string}:${string}`, any>[]): Delegation<Capabilities>[]
Get delegations created by the agent for others.
Parameters
- Optional caps: Capability<Ability, `${string}:${string}`, any>[]
  
  Capabilities to filter by. Empty or undefined caps with return all the delegations.
Returns Delegation<Capabilities>[]
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:85

delegationsWithMeta

delegationsWithMeta(caps?: Capability<Ability, `${string}:${string}`, any>[]): {
delegation: Delegation<Capabilities>;
meta: DelegationMeta;
}[]
Get delegations created by the agent for others and their metadata.
Parameters
- Optional caps: Capability<Ability, `${string}:${string}`, any>[]
  
  Capabilities to filter by. Empty or undefined caps with return all the delegations.
Returns {
delegation: Delegation<Capabilities>;
meta: DelegationMeta;
}[]
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:91

did

did(): `did:${string}:${string}`
Returns `did:${string}:${string}`
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:59

execute

execute<C_1, I>(...invocations: I): Await<InferServiceInvocations<I, Service>>
Execute invocations on the agent's connection

Example
```
const i1 = await agent.invoke(Space.info, {})
const i2 = await agent.invoke(Space.recover, {
  nb: {
    identity: 'mailto:hello@web3.storage',
  },
})

const results = await agent.execute2(i1, i2)
```
Type Parameters
- C_1 extends Capability<Ability, `${string}:${string}`, any, C_1>
- I extends [ServiceInvocation<C_1, Service>, ...ServiceInvocation<C_1, Service>[]]
Parameters
- Rest ...invocations: I
Returns Await<InferServiceInvocations<I, Service>>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:222

getSpaceInfo

getSpaceInfo(space?: URI<"did:">): Promise<Selectable<SpaceTable> & {
error?: undefined;
}>
Get Space information from Access service
Parameters
- Optional space: URI<"did:">
Returns Promise<Selectable<SpaceTable> & {
error?: undefined;
}>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:257

importSpaceFromDelegation

importSpaceFromDelegation(delegation: Delegation<Capabilities>): Promise<{
    did: `did:${string}:${string}`;
    meta: SpaceMeta;
    proof: Delegation<[{
        can: "*";
        nb?: InferCaveats<{}>;
        with: URI<"did:">;
    }]>;
}>
Import a space from a '*' delegation
Parameters
- delegation: Delegation<Capabilities>
Returns Promise<{
    did: `did:${string}:${string}`;
    meta: SpaceMeta;
    proof: Delegation<[{
        can: "*";
        nb?: InferCaveats<{}>;
        with: URI<"did:">;
    }]>;
}>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:114

invoke

invoke<A_1, R_1, CAP_1, C_2>(cap: CAP_1, options: InvokeOptions<A_1, R_1, CAP_1>): Promise<IssuedInvocationView<InferInvokedCapability<CAP_1>>>
Creates an invocation for the given capability with Agent's proofs, service, issuer and space.

Example
```
const recoverInvocation = await agent.invoke(Space.recover, {
  nb: {
    identity: 'mailto: email@gmail.com',
  },
})

await recoverInvocation.execute(agent.connection)
// or
await agent.execute(recoverInvocation)
```
Type Parameters
- A_1 extends Ability
- R_1 extends `${string}:${string}` & Phantom<{
  protocol: `${string}:`;
  }, R_1>
- CAP_1 extends TheCapabilityParser<CapabilityMatch<A_1, R_1, C_2>, CAP_1>
- C_2 extends Caveats = {}
Parameters
- cap: CAP_1
- options: InvokeOptions<A_1, R_1, CAP_1>
Returns Promise<IssuedInvocationView<InferInvokedCapability<CAP_1>>>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:246

invokeAndExecute

invokeAndExecute<A, R, CAP, C>(cap: CAP, options: InvokeOptions<A, R, CAP>): Promise<InferServiceInvocationReturn<InferInvokedCapability<CAP>, Service>>
Invoke and execute the given capability on the Access service connection
```
await agent.invokeAndExecute(Space.recover, {
  nb: {
    identity: 'mailto: email@gmail.com',
  },
})

// sugar for
const recoverInvocation = await agent.invoke(Space.recover, {
  nb: {
    identity: 'mailto: email@gmail.com',
  },
})

await recoverInvocation.execute(agent.connection)
```
Type Parameters
- A extends Ability
- R extends `${string}:${string}` & Phantom<{
  protocol: `${string}:`;
  }, R>
- CAP extends TheCapabilityParser<CapabilityMatch<A, R, C>, CAP>
- C extends Caveats = {}
Parameters
- cap: CAP
- options: InvokeOptions<A, R, CAP>
Returns Promise<InferServiceInvocationReturn<InferInvokedCapability<CAP>, Service>>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:202

peer

peer(channel: Channel): Peer
Parameters
- channel: Channel
Returns Peer
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:251

proofs

proofs(caps?: Capability<Ability, `${string}:${string}`, any>[]): Delegation<Capabilities>[]
Get all the proofs matching the capabilities

Proofs are delegations with an audience matching agent DID.
Parameters
- Optional caps: Capability<Ability, `${string}:${string}`, any>[]
  
  Capabilities to filter by. Empty or undefined caps with return all the proofs.
Returns Delegation<Capabilities>[]
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:79

recover

recover(email: string, opts?: {
    signal?: AbortSignal;
}): Promise<Delegation<[{
    can: "*";
    nb?: InferCaveats<{}>;
    with: URI<"did:">;
}]>[]>
Parameters
- email: string
- Optional opts: {
  signal?: AbortSignal;
  }
  - Optional signal?: AbortSignal
Returns Promise<Delegation<[{
    can: "*";
    nb?: InferCaveats<{}>;
    with: URI<"did:">;
}]>[]>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:129

registerSpace

registerSpace(email: string, opts?: {
signal?: AbortSignal;
}): Promise<void>
Invokes voucher/redeem for the free tier, wait on the websocket for the voucher/claim and invokes it

It also adds a full space delegation to the service in the voucher/claim invocation to allow for recovery
Parameters
- email: string
- Optional opts: {
  signal?: AbortSignal;
  }
  - Optional signal?: AbortSignal
Returns Promise<void>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:166

removeExpiredDelegations

removeExpiredDelegations(): Promise<void>
Clean up any expired delegations.

Returns Promise<void>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:71

setCurrentSpace

setCurrentSpace(space: `did:${string}:${string}`): Promise<`did:${string}:${string}`>
Sets the current selected space

Other methods will default to use the current space if no resource is defined
Parameters
- space: `did:${string}:${string}`
Returns Promise<`did:${string}:${string}`>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:143

`Static` create

create(init?: Partial<AgentDataModel>, options?: AgentOptions & AgentDataOptions): Promise<Agent>
Create a new Agent instance, optionally with the passed initialization data.
Parameters
- Optional init: Partial<AgentDataModel>
- Optional options: AgentOptions & AgentDataOptions
Returns Promise<Agent>
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:41

`Static` from

from(raw: AgentDataExport, options?: AgentOptions & AgentDataOptions): Agent
Instantiate an Agent from pre-exported agent data.
Parameters
- raw: AgentDataExport
- Optional options: AgentOptions & AgentDataOptions
Returns Agent
- Defined in node_modules/@web3-storage/access/dist/src/agent.d.ts:48

Class Agent

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

data: AgentData

Optional options: AgentOptions

Returns Agent

Properties

Private #private

connection

url

Accessors

issuer

Returns Signer<`did:${string}:${string}`, SigAlg>

meta

Returns AgentMeta

spaces

Returns Map<`did:${string}:${string}`, SpaceMeta>

Methods

addProof

Parameters

delegation: Delegation<Capabilities>

Returns Promise<void>

createSpace

Parameters

Optional name: string

Returns Promise<{ did: `did:key:${string}`; meta: SpaceMeta; proof: Delegation<[ToDeriveClaim<{ can: "*"; nb?: InferCaveats<{}>; with: URI<"did:">; }>]>; }>

currentSpace

Returns undefined | `did:${string}:${string}`

currentSpaceWithMeta

Returns undefined | { capabilities: any[]; did: `did:${string}:${string}`; meta: undefined | SpaceMeta; proofs: Delegation<Capabilities>[]; }

delegate

Parameters

options: DelegationOptions

Returns Promise<Delegation<Capabilities>>

delegations

Parameters

Optional caps: Capability<Ability, `${string}:${string}`, any>[]

Returns Delegation<Capabilities>[]

delegationsWithMeta

Parameters

Optional caps: Capability<Ability, `${string}:${string}`, any>[]

Returns { delegation: Delegation<Capabilities>; meta: DelegationMeta; }[]

did

Returns `did:${string}:${string}`

execute

Example

Type Parameters

C_1 extends Capability<Ability, `${string}:${string}`, any, C_1>

I extends [ServiceInvocation<C_1, Service>, ...ServiceInvocation<C_1, Service>[]]

Parameters

Rest ...invocations: I

Returns Await<InferServiceInvocations<I, Service>>

getSpaceInfo

Parameters

Optional space: URI<"did:">

Returns Promise<Selectable<SpaceTable> & { error?: undefined; }>

importSpaceFromDelegation

Parameters

delegation: Delegation<Capabilities>

Returns Promise<{ did: `did:${string}:${string}`; meta: SpaceMeta; proof: Delegation<[{ can: "*"; nb?: InferCaveats<{}>; with: URI<"did:">; }]>; }>

invoke

Example

Type Parameters

A_1 extends Ability

R_1 extends `${string}:${string}` & Phantom<{ protocol: `${string}:`; }, R_1>

CAP_1 extends TheCapabilityParser<CapabilityMatch<A_1, R_1, C_2>, CAP_1>

C_2 extends Caveats = {}

Parameters

cap: CAP_1

options: InvokeOptions<A_1, R_1, CAP_1>

Returns Promise<IssuedInvocationView<InferInvokedCapability<CAP_1>>>

invokeAndExecute

Type Parameters

`Optional` options: AgentOptions

`Private` #private

`Optional` name: string

Returns Promise<{
did: `did:key:${string}`;
meta: SpaceMeta;
proof: Delegation<[ToDeriveClaim<{
can: "*";
nb?: InferCaveats<{}>;
with: URI<"did:">;
}>]>;
}>

Returns undefined | {
capabilities: any[];
did: `did:${string}:${string}`;
meta: undefined | SpaceMeta;
proofs: Delegation<Capabilities>[];
}

`Optional` caps: Capability<Ability, `${string}:${string}`, any>[]

`Optional` caps: Capability<Ability, `${string}:${string}`, any>[]

Returns {
delegation: Delegation<Capabilities>;
meta: DelegationMeta;
}[]

`Rest` ...invocations: I

`Optional` space: URI<"did:">

Returns Promise<Selectable<SpaceTable> & {
error?: undefined;
}>

Returns Promise<{
did: `did:${string}:${string}`;
meta: SpaceMeta;
proof: Delegation<[{
can: "*";
nb?: InferCaveats<{}>;
with: URI<"did:">;
}]>;
}>

R_1 extends `${string}:${string}` & Phantom<{
protocol: `${string}:`;
}, R_1>

R extends `${string}:${string}` & Phantom<{
protocol: `${string}:`;
}, R>

`Optional` caps: Capability<Ability, `${string}:${string}`, any>[]

`Optional` opts: {
signal?: AbortSignal;
}

`Optional` signal?: AbortSignal

Returns Promise<Delegation<[{
can: "*";
nb?: InferCaveats<{}>;
with: URI<"did:">;
}]>[]>

`Optional` opts: {
signal?: AbortSignal;
}

`Optional` signal?: AbortSignal

`Static` create

`Optional` init: Partial<AgentDataModel>

`Optional` options: AgentOptions & AgentDataOptions

`Static` from

`Optional` options: AgentOptions & AgentDataOptions