From f755c5ee466c7ef9200c57d2f07d3e1508af0269 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Wed, 14 Nov 2018 14:59:03 +0100
Subject: [PATCH] feat: scaffolding for window.ipfs.enable

This simply changes the flow and API for getting IPFS proxy instance,
does not implement UX nor decrease the size of injected content script.
---
 add-on/src/contentScripts/ipfs-proxy/page.js | 20 ++++++++++++++++++--
 docs/window.ipfs.md                          | 17 ++++++++++++-----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/add-on/src/contentScripts/ipfs-proxy/page.js b/add-on/src/contentScripts/ipfs-proxy/page.js
index 8864348ec..e150d8b4b 100644
--- a/add-on/src/contentScripts/ipfs-proxy/page.js
+++ b/add-on/src/contentScripts/ipfs-proxy/page.js
@@ -1,7 +1,23 @@
 'use strict'
 
-const { createProxyClient } = require('ipfs-postmsg-proxy')
 const _Buffer = Buffer
 
+// TODO: this should not be injected by default into every page,
+// instead should be lazy-loaded when .enable() method is called for the first time
+const { createProxyClient } = require('ipfs-postmsg-proxy')
+
+function windowIpfs2 () {
+  return Object.freeze({
+    enable: async (args) => {
+      // TODO:  pass args to ipfs-postmsg-proxy constructor
+      // to trigger user prompt if list of requested capabilities is not empty
+      const proxyClient = createProxyClient()
+      console.log('Called window.ipfs.enable', args)
+      return proxyClient
+    }
+  })
+}
+
+// TODO: we should remove Buffer and add support for Uint8Array/ArrayBuffer natively
 window.Buffer = window.Buffer || _Buffer
-window.ipfs = window.ipfs || createProxyClient()
+window.ipfs = window.ipfs || windowIpfs2()
diff --git a/docs/window.ipfs.md b/docs/window.ipfs.md
index 5dc97cb3d..08c2e698e 100644
--- a/docs/window.ipfs.md
+++ b/docs/window.ipfs.md
@@ -25,15 +25,18 @@ IPFS Companion is exposing a subset of IPFS APIs as `window.ipfs` on every webpa
 
 This means websites can detect that `window.ipfs` already exists and use it instead of spawning own `js-ipfs` node, which saves resources, battery etc.
 
-For more context, see original issue: [Expose IPFS API as window.ipfs #330](https://github.com/ipfs-shipyard/ipfs-companion/issues/330)
+For more context, see:
+- first iteration: [Expose IPFS API as window.ipfs #330](https://github.com/ipfs-shipyard/ipfs-companion/issues/330)
+- second iteration: [window.ipfs 2.0](https://github.com/ipfs-shipyard/ipfs-companion/issues/589)
 
 ## Creating applications using `window.ipfs`
 
 If a user has installed IPFS companion, `window.ipfs` will be available as soon as the first script runs on your web page, so you'll be able to detect it using a simple `if` statement:
 
 ```js
-if (window.ipfs) {  
-  await ipfs.id()
+if (window.ipfs && window.ipfs.enable) {
+  const ipfs = await window.ipfs.enable( { capabilities: ['id'] } )
+  console.log(await ipfs.id())
 } else {
   // Fallback
 }
@@ -42,8 +45,10 @@ if (window.ipfs) {
 To add and get content, you could do something like this:
 
 ```js
-if (window.ipfs) {
+if (window.ipfs && window.ipfs.enable) {
   try {
+    const capabilities = ["add","cat"]
+    const ipfs = await window.ipfs.enable({capabilities})
     const [{ hash }] = await ipfs.add(Buffer.from('=^.^='))
     const data = await ipfs.cat(hash)
     console.log(data.toString()) // =^.^=
@@ -92,9 +97,11 @@ Note these might have been re-worded already. Please send a PR.
 
 ## What _is_ a `window.ipfs`?
 
+It is an endpoint that enables you to obtain IPFS API instance.
+
 Depending how IPFS companion is configured, you may be talking directly to a `js-ipfs` node running in the companion, a `go-ipfs` daemon over `js-ipfs-api` or a `js-ipfs` daemon over `js-ipfs-api` and potentially others in the future.
 
-Note that `window.ipfs` is _not_ an instance of `js-ipfs` or `js-ipfs-api` but is a proxy to one of them, so don't expect to be able to detect either of them or be able to use any undocumented or instance specific functions.
+Note that object returned by `window.ipfs.enable` is _not_ an instance of `js-ipfs` or `js-ipfs-api` but is a proxy to one of them, so don't expect to be able to detect either of them or be able to use any undocumented or instance specific functions.
 
 See the [js-ipfs](https://github.com/ipfs/js-ipfs#api)/[js-ipfs-api](https://github.com/ipfs/js-ipfs-api#api) docs for available functions. If you find that some new functions are missing, the proxy might be out of date. Please check the [current status](https://github.com/tableflip/ipfs-postmsg-proxy#current-status) and submit a PR.