# Web5 JS DWN Methods - Simplified Version

### Default to local/agent DWN

For all of the methods, the default is to target your agent's DWN - the DWN of the agent the application is _connected_ to. The belief/intent was to simplify the most trivial getting started cause where an individual may not have much knowledge of Web5 / DWN terminology yet. By defaulting to local/agent, there is no need to introduce the idea of agents and multiple DWNs right away.

However, the case might be made that this implicit default ends up leading to more confusion in the long run. If there's a strong opinion in the direction of making it an explicit choice, then we can make `store` a required property and `store: 'agent'` will then have to be specified on all local writes.

---

### `write()` / `create()`

All 15 permutations are possible, but to keep this short, I'll highlight 7 of what I am expecting will the most common scenarios. Remains to be seen and we won't really know is this hunch is correct or dead wrong. However, worst case this approach works for all 15.

Intuition that this is > 50% of the use cases:
- if local, always send first
- if remote, always send after local
- if another DID, always send after local and remote

and even if its not, again, we've got all 15 scenarios covered. If its 2 remote DID parties then the permutations increase but they can still all be covered.

**A. Your own local:**

// write to your agent's dwn (aka write to the dwn of the agent an app is _connected_ to)
await web5.dwn.records.create({
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

**B. Your own local + your own remote:**

// write to your agent's dwn
const { record } = await web5.dwn.records.create({
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

// write to your DID-relative dwns (a.k.a cloud dwns)
await record.send(aliceDid)

**C. Your own local + your own remote + someone else's remote:**

// write to your agent's dwn
const { record } = await web5.dwn.records.create({
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

// write to your DID-relative dwns (a.k.a cloud dwns)
await record.send(aliceDid);

// write to Bob's DWN
await record.send(bobDid);

**D. Your own local + someone else's remote:**

// write to your agent's dwn
const { record } = await web5.dwn.records.create({
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

// write to Bob's DWN
await record.send(bobDid);

**E. Your own remote + someone else's remote:**

// write to your DID-relative dwns (a.k.a cloud dwns)
const { record } = await web5.dwn.records.create({
  store: false,
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

// write to Bob's DWN
await record.send(alicDid);
await record.send(bobDid);

**F. Your own remote:**

// write to your DID-relative dwns (a.k.a cloud dwns)
await web5.dwn.records.create({
  store: false,
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

await record.send(alicDid);

**G. Someone else's remote:**

While I understand `store: false` may illicit some raised eyebrows, part of the aspect of
this that I think is a useful affordance is that it requires that the application
explicitly specify that the record is **NOT** to be retained by the sending entity **UNLESS**
a subsequent invocation of `record.store()` is performed.

An alternative is to not store the record in any of the active DID's DWNs if the `store` property is left undefined, but this _seems_ worse in terms of unexpected consequences.

// write to your agent's dwn
const { record } = await web5.dwn.records.create({
  store: false,
  data: 'hi',
  message: {
    "schema": 'whatever'
  }
});

// write to Bob's DWN
record.send(bobDid);

---

### How about record encryption?

We've received feedback from within team TBD and community members on Discord that the following example:

const { record, status } = await web5.dwn.records.create({
  to: bobDid,
  message: {
    "schema": 'whatever'
  },
  data: 'hi'
});

would be interpreted as taking the action: of "writing a record to bob's dwn", which it does not unless `record.send(bobDid)` is called, as in this example:

// writes to your local / agent DWN
const { record, status } = await web5.dwn.records.create({
  message: {
    "schema": 'whatever'
  },
  data: 'hi'
});

// writes to Bob's DWN
record.send(bobDid);

To address this the examples above do not involve specifying `to: bobDid` within the `write()` / `create()` message options for all of the cases where encryption is not desired.

Instead, if the record is to be encrypted, the message would be:

// writes to your local / agent DWN
const { record, status } = await web5.dwn.records.create({
  encryptFor: bobDid,
  message: {
    "schema": 'whatever'
  },
  data: 'hi'
});

// writes to Bob's DWN
record.send(bobDid);

The semantics of `encryptFor` then invovle both enabling encryption for the record and explicitly specifying who's public keys will be used such that `bobDid` will be the only one that can decrypt the record using a `bobDid` public key to first decrypt the symmetric key, and then using that symmetric key to decrypt the record data.

---

## All other `web5.dwn.*.*` methods

**Notes**
- `recipient {string}` specifies another DID's DWN to query/read/delete
- If this term causes heart burn how about
- `from` as in `QUERY FROM` / `READ FROM` / `DELETE FROM`
- `store {'agent' | 'endpoints'}` specifies which DWN to query/read/delete from

### `query()`

1. Your local

web5.dwn.records.query({
  message: {
    filter: {
      contextId: thread.contextId
    }
  }
});

2. Your remote

web5.dwn.records.query({
  recipient: aliceDid,
  message: {
    filter: {
      contextId: thread.contextId
    }
  }
});

3. Someone else's remote

web5.dwn.records.query({
  recipient: bobDid,
  message: {
    filter: {
      contextId: thread.contextId
    }
  }
});

### `read()`

1. Your local

web5.dwn.records.read({
  message: {
    recordId: thread.recordId
  }
});

2. Your remote

web5.dwn.records.query({
  recipient: aliceDid,
  message: {
    recordId: thread.recordId
  }
});

3. Someone else's remote

web5.dwn.records.query({
  recipient: bobDid,
  message: {
    recordId: thread.recordId
  }
});

### `delete()`

1. Your local

web5.dwn.records.read({
  message: {
    recordId: thread.recordId
  }
});

2. Your remote

web5.dwn.records.read({
  recipient: aliceDid,
  message: {
    recordId: thread.recordId
  }
});

3. Someone else's remote

web5.dwn.records.read({
  recipient: bobDid,
  message: {
    recordId: thread.recordId
  }
});