chore: update remote pinning api implementation

Author: Gozala

packages/interface-ipfs-core/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": [
+    "src",
+    "type",
+    "package.json",
+  ]
+}

packages/interface-ipfs-core/type/basic.ts

@@ -0,0 +1,15 @@
+/**
+ * Common options across all cancellable requests.
+ */
+export interface AbortOptions {
+  /**
+   * Can be provided to a function that starts a long running task, which will
+   * be aborted when signal is triggered.
+   */
+  signal?: AbortSignal
+  /**
+   * Can be provided to a function that starts a long running task, which will
+   * be aborted after provided timeout (in ms).
+   */
+  timeout?: number
+}

packages/interface-ipfs-core/type/index.ts

@@ -0,0 +1,19 @@
+
+import * as Basic from './basic'
+import * as PinRemote from './pin/remote'
+
+export { Basic, PinRemote }
+
+// class Foo implements PinRemote.API {
+
+// }
+// // export { Basic, PinRemote }
+
+// declare namespace Lib {
+//   import { AbortOptions } from '/basic'
+//   import { API } from './pin/remote'
+// }
+
+// export { Lib }
+
+// // export { Lib }

packages/interface-ipfs-core/type/pin/remote.ts

@@ -0,0 +1,106 @@
+import CID from 'cids'
+import Multiaddr from 'multiaddr'
+import { API as Service } from './remote/service'
+import { AbortOptions } from '../basic'
+
+export interface API {
+  /**
+   * API for configuring remote pinning services.
+   */
+  service: Service
+
+  /**
+   * Stores an IPFS object(s) from a given path to a remote pinning service.
+   */
+  add(cid:CID, options:AddOptions & AbortOptions):Promise<Pin>
+
+  /**
+   * Returns a list of matching pins on the remote pinning service.
+   */
+  ls(query: Query & AbortOptions): AsyncIterable<Pin>
+
+  /**
+   * Removes a single pin object matching query allowing it to be garbage
+   * collected (if needed). Will error if multiple pins mtach provided
+   * query. To remove all matches use `rmAll` instead.
+   */
+  rm(query: Query & AbortOptions): Promise<void>
+
+  /**
+   * Removes all pin object that match given query allowing them to be garbage
+   * collected if needed.
+   */
+  rmAll(query: Query & AbortOptions): Promise<void>
+}
+
+export interface AddOptions extends RemoteServiceOptions {
+  /**
+   * Optional name for pinned data; can be used for lookups later (max 255
+   * characters)
+   */
+  name?: string
+
+  /**
+   * Optional list of multiaddrs known to provide the data (max 20).
+   */
+  origins?: Multiaddr[]
+
+  /**
+   * If true, will add to the queue on the remote service and return
+   * RequestID immediately. If false or amitted will wait until pinned on the
+   * remote service.
+   */
+  background?: boolean
+}
+
+/**
+ * Reperesents query for matching pin objects.
+ */
+export interface Query extends RemoteServiceOptions {
+  /**
+   * If provided, will only include pin objects that have a CID from the given
+   * set.
+   */
+  cid?: CID[]
+  /**
+   * If passed, will only include pin objects with names that have this name
+   * (case-sensitive, exact match).
+   */
+  name?: string
+
+  /**
+   * Customize the text matching strategy applied when name filter is present.
+   * Uses "exact" if omitted.
+   */
+  match?: TextMatchingStrategy
+
+  /**
+   * Return pin objects for pins that have one of the specified status values.
+   * If omitted treated as ["pinned"]
+   */
+  status?: Status[]
+}
+
+export interface RemoteServiceOptions {
+  /**
+   * Name of the remote pinning service to use.
+   */
+  service: string
+}
+
+export interface Pin {
+  status: Status
+  cid: CID
+  name?: string
+}
+
+export type TextMatchingStrategy =
+  | 'exact'
+  | 'iexact'
+  | 'partial'
+  | 'ipartial'
+export type Status =
+  | 'queued'
+  | 'pinning'
+  | 'pinned'
+  | 'failed'

packages/interface-ipfs-core/type/pin/remote/service.ts

@@ -0,0 +1,74 @@
+import { AbortOptions } from '../../basic'
+
+export interface API {
+  /**
+   * Registers remote pinning service with a given name. Errors if service
+   * with the given name is already registered.
+   */
+  add(name: string, credentials:Credentials & AbortOptions): Promise<void>
+
+  /**
+   * Unregisteres remote pinning service with a given name. If service with such
+   * name isn't registerede this is a noop.
+   */
+  rm(name: string, options?:AbortOptions):Promise<void>
+
+  /**
+   * List registered remote pinning services.
+   */
+  ls(options:ListOptions & AbortOptions):Promise<RemotePinService[]>
+}
+
+export interface Credentials {
+  /**
+   * Service URL
+   */
+  url: URL
+  /**
+   * Service key
+   */
+  key: string
+}
+
+export interface RemotePinService {
+  /**
+   * Service name
+   */
+  service: string
+  /**
+   * Service URL
+   */
+  url: URL
+  /**
+   * Pin count on the remote service. It is fetched from the remote service and
+   * is done only if `pinCount` option is used. Furthermore it may not be
+   * present if service was unreachable.
+   */
+  stat?: Stat
+}
+
+export interface ListOptions {
+  /**
+   * If `true` will try to fetch and include current pin count on the remote
+   * service.
+   */
+  stat?: boolean
+}
+
+export type Stat = ValidStat | InvalidStat
+
+type ValidStat = {
+  status: 'valid'
+  pinCount: PinCount
+}
+
+type InvalidStat = {
+  status: 'invalid'
+  pinCount?: void
+}
+export type PinCount = {
+  queued: number,
+  pinning: number,
+  pinned: number,
+  failed: number
+}

packages/ipfs-http-client/src/pin/index.js

@@ -1,10 +1,12 @@
 'use strict'
 
+const Remote = require('./remote')
+
 module.exports = config => ({
   add: require('./add')(config),
   addAll: require('./add-all')(config),
   ls: require('./ls')(config),
   rm: require('./rm')(config),
   rmAll: require('./rm-all')(config),
-  remote: require('./remote')(config)
+  remote: new Remote(config)
 })