API

prs-lib 暴露一个 PRS 类，PRS 主要对 REST API 进行了封装，方便开发者对资源进行操作。同时也对常用的加解密过程进行了封装，以静态方法的形式（PRS.util）暴露出来。

PRS

const prs = new PRS(options)

options.env: string, 设置开发环境。正式环境为'prod', 开发环境为'dev'.
options.debug: boolean, 开启调试日志，开启后 SDK 会把网络请求、错误消息等信息输出到 IDE 的日志窗口.
options.address: string, 授权用户的 address.
options.token: string, 授权用户的 access token.
options.privateKey: string, 授权用户的 privateKey.
options.host: string, 可选项，指定 api 服务器，多用于调试
options.onApiError: (error, response) => any, 可选项，api 请求错误的 callback，设置之后，在遇到 api 报错时，不会 reject，而是返回 callback 的处理结果.
options.onApiSuccess: (response) => any, 可选项，api 请求成功的 callback，设置之后，在遇到 api 成功时，会返回处理后的结果.

注：关于 token 和 privateKey，dapp 代表用户时，采用 token（因为拿不到用户的 privateKey）。而用户或是 dapp 代表自己身份时（能拿到 privateKey 时），可以使用 privateKey；区别在于，在签名时，使用 token 的身份会在服务端进行签名，而有 privateKey 的身份可以在本地签名。关于 onApiError 和 onApiSuccess，默认情况下，返回结果是 superagent 的相应结果，api 服务器的结果在 res.body 中，为了避免每次请求完获取 res.body ，可以设置 onApiSuccess：res => res.body。

初始化完毕后，可以调用以下方法

prs.config
- getHost
prs.draft
- create
- update
- delete
- getById
- getDrafts
prs.dapp
prs.file
prs.finance
prs.block
- getByRIds
prs.contract
- getTemplates
- create
- getByRId
- bind
prs.order
prs.keystore
- loginByEmail
- loginByPhone
prs.user
prs.subscription

另外 PRS 还存在静态方法

PRS.util

所有模块的示例都在 prs-sdk/samples 目录下给出，例如 prs.dapp 的示例文件对应为 prs-sdk/samples/dapp.example.js

prs-lib 和 prs-utility 均提供 type 文件，并且都是一层薄封装，推荐配合源码查看。

prs.config

可访问当前 prs 实例创建时的身份信息，比如 prs.config.env 对应构造函数传入的 options.env。

另外提供了函数，获取 api 的 host

config.getHost

getHost(): string;

returns: string # PRS 的 host

prs.draft

封装了对草稿的操作

draft.create

创建草稿操作

create(draft: DraftContent): Promise

params: Draft
- Draft.title: string
- Draft.content: string
- Draft.mimeType: string
returns: Promise<Response>
- Response.body
  - draftId: number

draft.update

更新草稿

update(id: string, draft: DraftContent): Promise

params:
- draftId: number
- draftNew: Draft
returns: Promise<Response>
- Response.body: boolean

draft.delete

删除草稿

delete(id: string): Promise

params:
- draftId: string
returns: Promise<Response>
- Response.body: boolean

draft.getById

根据 id 获取草稿

getById(id: string): Promise

params:
- draftId: string
returns: Promise<Response>
- Response.body
  - file: object
    - id: string
    - other props..
  - user: object
    - address: string
    - name: string
    - avatar: string
    - other props..

draft.getDrafts

获取所有 draft

getDrafts(): Promise

returns: Promise<Response>
- Response.body
  - data: object
    - total: number
    - list: [Draft]

prs.dapp

在创建 prs 实例后，可以使用 prs.dapp 进行对 dapp 接口的交互

dapp.create

创建接口，调用接口进行 dapp 的创建，为了避免名称冲突，另外还提供了 dapp 名称的查询接口： isNameExist。

isNameExist(name: string): Promise

returns: Promise<Response>
- Response.body
  - isExist: boolean

create(dapp: DappContent): Promise

params:
- dapp.name: string
- dapp.description: string
- dapp.url: string
- dapp.redirectUrl: string
- dapp.logo: string
returns: Promise
- res.data
  - address: string
  - privateKey: string
  - other meta data

注意，传入参数 name，description，url 和 redirectUrl 存在长度 < 255 的限制，超过时会被截断。logo 参数为图片的 base64 的字符串。

dapp.update

更新接口，更新 dapp 信息

update(address: string, dapp: DappContent): Promise

params:
- address: string
- dapp(同 create 参数)
returns: Promise(同 create 返回)

dapp.delete

delete(address: string): Promise

params:
- address: string
returns: Promise<Response>
- Response.body
  - deletedAt: string(UTC 时间)

dapp.getByAddress

getByAddress(address: string): Promise

params:
- address: string
returns: Promise(同 create 返回)

dapp.getAuthorizeUrl

引导用户使用浏览器访问，进行授权

getAuthorizeUrl(appAddress: string): Promise

params:
- address: string
returns: Promise<Response>
- Response.body: string

dapp.webAuthorize

向目标 dapp 进行授权，传入 dapp 地址，返回 code 和 redirectUrl。目标 dapp 通常会实现 authByCode 接受授权。

webAuthorize(appAddress: string): Promise

params:
- address: string
returns: Promise<Response>
- Response.body
  - code: string
  - redirectUrl: string

dapp.authByCode

dapp 通过 code 接受授权，获取代表用户身份的 token

authByCode(code: string, appAddress: string, appPrivateKey: string)

params:
- code: string
- address: string (dapp 的 address)
- privateKey: string (dapp 的 private key)
returns: Promise<Response>
- Response.body
  - token: string
  - appAuthentication
    - userAddress: string
    - signature: string
    - appAddress: string
    - authAddress: string

dapp.deauthenticate

取消对 dapp 的授权

deauthenticate(appAddress: string, authAddress: string): Promise

params:
- appAddress: string
- authAddress: string
returns: Promise<Response>
- Response.body
  - appAuthentication
    - status: 'CANCELED'
    - other meta data

dapp.listAuthorized

获取所有已授权的 dapp 信息

listAuthorized(): Promise;

returns: Promise<Response>
- Response.body

prs.file

prs.file 封装了对文件的签名、获取、打赏等功能

file.signByFileReader

限定在浏览器中使用，使用 filereader 进行签名

signByFileReader(
data: FileData,
onUploadProgress?: (event: SuperAgentUploadEvent) => any,
onHashProgress?: (percent: number) => any): Promise;

onUploadProgress 为上传的进度事件，event.percent 可以访问到事件触发时上传的进度。 onHashProgress 为 hash 进度。

签名流程为，FileReader 读取数据并且算出文件的 hash 值，完成之后进行上传上链。

interface FileData {
  file?: any;
  stream?: any;
  buffer?: any;
  filename?: string;
  source?: string;
  originUrl?: string;
  category?: string;
  projectId?: string | number;
}

file.signByStream

限定在 node 项目使用，对 Readable Streams 进行签名

signByStream(data: FileData, meta: object): Promise

params:
- data
  - stream: Readable
  - filename: string
  - titlle: string
  - source (optional): string
  - originUrl (optional): string
  - category (optional): string
  - projectId (optional): string
- meta: 任意结构化的数据，最终将会以 JSON 字符串的形式存储
returns: Promise<Response>
- Response.body
  - cache
    - msghash: string
    - rId: string
    - address: string
    - 其他属性
  - block: object （参考PRS 协议）

file.signByBuffer

对 buffer 进行签名

signByBuffer(data: FileData, meta: object): Promise

params:
- data
  - buffer: Buffer
  - filename: string
  - titlle: string
  - source (optional): string
  - originUrl (optional): string
  - category (optional): string
  - projectId (optional): string
returns: Promise(同上)

file.getByRId

根据 id 查询文件记录

getByRId(rId: string): Promise

params:
- id: string
returns: Promise<Response>
- Response.body
  - block 同上
  - cache 同上
  - contracts: [Contract(详见下)]

file.getByMsghash

跟据 hash 查询文件记录

getByMsghash(msghash: string): Promise

参数和返回结果同 getByRId

file.getFeeds

根据用户的 address 获取该用户所有的文件记录

getFeeds(address: string, options?: { limit?: number, offset?: number, [key: string]: any }): Promise;

params:
- address: string
- pageOpt:
  - limit: number
  - offset: number
returns: Promise<Response>
- Response.body
  - author: object
    - name: string
    - url: string
    - avatar: string
  - items: array
    - id: string
    - title: string
    - url: string
    - ... 其他属性
  - _total: number

file.reward

打赏（注意这里是 PRS 站内行为，不上链）

reward(rId: string, amount: number, options?: { memo?: string, comment?: string, header?: object }): Promise;

params:
- rId: string，被打赏的文件 id
- amount: number，数额
- memo: string，可选
- comment: string, 可选
- header: object, 打赏金额超过一定量时，需要提供额外的 header 进行身份的二次确认
returns: Promise<Response>
- Response.body
  - id: number
  - fromAddress: string
  - toAddress: string
  - amount: string
  - comment: string
  - status: string
  - provider: string
  - forFileRId: string
  - viewToken: string

prs.finance

prs.finance 封装了对钱包的操作，包括充值、提取等。

finance.getWallet

获取钱包接口

getWallet(): Promise

returns: Promise<Response>
- Response.body
  - balance
    - income: string
    - expenditure: string
    - frozen: string
    - balance: string
    - available: string
  - summary
    - ALL: number
    - AWARD: number
    - WITHDRAW: number
    - BONUS: number
    - RECHARGE: number
    - TRANSFER: number
    - CONTRACT_LICENSE_PURCHASE: number
    - COUPON: number

finance.getTransactions

获取交易历史记录

getTransactions(opt: PageOpt): Promise

interface PageOpt {
  offset?: number;
  limit?: number;
}

params:
- offset: number
- limit: number
returns: Promise<Response>
- Response.body
  - list: array
    - fromAddress: string
    - toAddress: string
    - amount: string
    - other props...
  - total: number

finance.recharge

充值接口

recharge(amount: number): Promise

params:
- amount: number
returns: Promise<Response>
- Response.body
  - receipt: object
    - fromAddress: string
    - toAddress: string
    - amount: string
    - other props...

finance.withdraw

提现接口

withdraw(amount: number): Promise

params:
- amount: number
returns: Promise<Response>
- Response.body
  - receipt: object
    - fromAddress: string
    - toAddress: string
    - amount: string
    - other props...

prs.block

prs.block 提供对区块的查询功能。

block.getByRIds

getByRIds(rIds: [string], options?: { withDetail: boolean }): Promise;

params:
- ids: [string]
- withDetail: boolean
returns: Promise<Response>
- Response.body: [Block]

查询区块的信息，如果 withDetail 为 true，那么每个区块将会携带一些额外信息（比如用户名称、头像等）

prs.contract

prs.contract 封装了对合约的操作，包括创建、绑定合约，交易授权等等。

contract.getTemplates

getTemplates(type: string): Promise

params: type: string
returns: Promise<Response>
- Response.body
  - total: number
  - list: [Contract]
    - Contract.code: string
    - Contract.name: string
    - Contract.description: string
    - Contract.licenses: [License]
      - License.type: string
      - License.currency: string
      - License.termtext: string

contract.create

创建合约

create(code: string, hashAlg: string): Promise

params:
- code: string
- hashAlg: string
returns: Promise<Response>
- Response.body
  - contract.rId: string

contract.getByRId

getByRId(rId: string): Promise;

params: rId: 合约 id
returns: Promise

contract.bind

绑定合约，需要提供合约 id，文件 id，以及受益人的地址。

bind({contractRId: string, fileRId: string, beneficiaryAddress: string}, hashAlg: string): Promise;

绑定合约会在链上创建一个新块

params
- contractRId: 合约 id
- fileRId: 文件 id
- beneficiaryAddress: 受益人地址
- hashAlg: hash 算法
returns: Promise<Response>
- Response.body
  - rId: stirng
  - type: string ('RECEIVER')
  - address: string
  - fileMsgHash: string # 文件相关元信息
  - file: string # 传入的 fileRId
  - contract: string # 传入的 contractRId
  - receiver: string # 传入的 beneficiaryAddress
  - version: number

contract.getContracts

getContracts(opt: PageOpt): Promise;

params
- opt.limit: number
- opt.offset: number
returns: Promise<Response>
- Response.body
  - total: number
  - list: [{file: File, contract: Contract, orderSummary: {total: number, amount: string}}]

prs.order

封装了订单相关的操作

order.create

create(contractRId: string, fileRId: string, licenseType: string): Promise

returns: Promise<Response>
- Response.body
  - rId: string # 链上的标志，可以用于查询块
  - type: string # 'SENDER'
  - file: string # fileRId
  - fileMsghash: string
  - contract: string # contractRId
  - address: string
  - receiver: string
  - license: string
  - price: string
  - currency: string
  - sender: string
  - traceId: string
  - paymentSnapshotId: string
  - senderWalletId: string
  - receiverWalletId: string

order.getOrdersByContractRId

获取与合约相关的订单情况

getOrdersByContractRId(contractRId: string, opt: PageOpt): Promise

params
- opt.limit: number
- opt.offset: number
returns: Promise<Response>
- Response.body
  - total: number
  - list: [Order]
    - Order: 同上创建返回的数据结构
  - orderSummary: object
    - total: number
    - amount: string # 数字字符串

order.getPurchasedOrders

获取当前身份已付款的订单情况

getPurchasedOrders(options?: { offset?: number, limit?: number, type?: string }): Promise;

params
- opt.limit: number
- opt.offset: number
returns: Promise<Response>
- Response.body
  - total: number
  - list: [{file: File, order: Order, contract: Contract}]

order.getOrderByRId

getOrderByRId(rId: string): Promise;

returns: Promise<Response>
- Response.body
  - order: Order

prs.keystore

实际为 pressone 的登录接口，可以根据邮箱登录，或是手机号和验证码（需要前端获取）登录，均返回 token 和 keystore 信息。

keystore.loginByEmail

loginByEmail(email: string, password: string): Promise

returns: Promise<Response>
- Response.body
  - token: string
  - keystore: sting # json string

keystore.loginByPhone

loginByPhone(phone: string, code: string): Promise;

returns: Promise<Response>
- Response.body
  - token: string
  - keystore: sting # json string

prs.user

对 pressone 站内的用户相关接口的操作，包括获取、编辑个人信息等

user.getByAddress

getByAddress(address: string): Promise

returns: Promise<Response>
- Response.body
  - address: string
  - avatar: string
  - title: string
  - 其他用户信息

user.editProfile

editProfile(profile: Profile): Promise

parmas: Profile
- Profile.name: string
- Profile.bio: string
- Profile.title: string
returns: 同上

user.uploadAvatar

uploadAvatar(avatarBase64String: string): Promise;

返回值同上

prs.subscription

封装了对订阅和推荐相关的操作

subscription.getSubscriptions

getSubscriptions(
      address: string,
      options?: { limit?: number, offset?: number, asCount?: boolean, isPersonal?: boolean | string, accountType?: string }
    ): Promise<any>;

params:
- address: 订阅者地址
returns: Promise<Response>
- Response.body
  - total: number
  - list: [SubscrptionData]

subscription.getSubscriptionJson

功能和上述类似，返回格式为 JSONFeed

getSubscriptionJson(
      address: string,
      options?: { limit?: number, offset?: number, asCount?: boolean, isPersonal?: boolean | string, accountType?: string }
    ): Promise<any>;

params:
- address: 订阅者地址
returns: Promise<Response>
- Response.body
  - version: string # json feed 的版本号
  - user_comment: string
  - title: string
  - home_page_url: string
  - feed_url: string
  - author: object
    - name: string
    - avater: string
    - urk: string
  - items: [SubscrptionData]
  - _total: number

subscription.getSubscribers

获取 address 的订阅者信息

getSubscribers(address: string, options: PageOpt): Promise;

params:
- address: 发布者地址
returns: Promise<Response>
- Response.body
  - total: number
  - list: [Subscriber]
    - Subscriber.name: string
    - Subscriber.avatar: string
    - Subscriber.subscriberAddress: string

subscription.subscribe

发起订阅

subscribe(address: string): Promise

params:
- address: 发布者地址
returns: Promise<Response>
- Response.body： empty

subscription.checkSubscription

检查订阅状态

checkSubscription(subscriberAddress: string, publisherAddress: string): Promise

returns: Promise<Response>
- Response.body
  - id: number
  - subscriberAddress: string
  - publisherAddress: string
  - createdAt: string # date string
  - updatedAt: string # date string

subscription.unsubscribe

取消订阅

unsubscribe(address: string): Promise;

params:
- address: 发布者地址
returns: Promise<Response>
- Response.body
  - fieldCount: number
  - affectedRows: number
  - insertId: number
  - info: string
  - serverStatus: number
  - warningStatus: number

subscription.getRecommendations

获取推荐列表

getRecommendations(offset: number, limit: number): Promise

returns: Promise<Response>
- Response.body: [Recommendation]
  - Recommendation.id: number
  - Recommendation.name: string
  - Recommendation.description: string
  - Recommendation.avatar: string
  - Recommendation.isOfficial: boolean
  - Recommendation.version: number

subscription.getRecommendationJson