# Class: Subscriptions

## Subscriptions(options)

Service class to handle interacting with the Cask subscriptions system

## Constructor

#### new Subscriptions(options)

Create an instance of the Subscriptions service.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` |  | See CaskSDK configuration.

See:
  - CaskSDK

### Methods

#### (async) activeSubscriptionCount(consumer, provider, planIdopt)

Return the number of active/trialing subscriptions a consumer has to a specific provider and plan.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`consumer` | string |  | Consumer address
`provider` | string |  | Provider address
`planId` | number | <optional> | Plan ID

#### (async) attachData(subscriptionId, data, optionsopt, authSigopt, privacyopt) → {Promise.<{tx: *}>}

Attach transferrable private data to a subscription.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`subscriptionId` |  |  |  |
`data` |  |  |  |
`options` |  | <optional> |  | Additional Options
`authSig` | object | <optional> |  | LIT authsig
`privacy` |  | <optional> | enc.mode.TRANSFERRABLE | privacy setting for attached data.

##### Returns:

Type
  Promise.<{tx: *}>

#### (async) attachedData(subscriptionId, optionsopt, authSigopt, privacyopt) → {Promise.<*>}

Get the transferrable private data attached to a subscription.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`subscriptionId` |  |  |  |
`options` |  | <optional> |  | Additional Options
`authSig` | object | <optional> |  | LIT authsig
`privacy` |  | <optional> | enc.mode.TRANSFERRABLE | privacy setting for attached data.

##### Returns:

Type
  Promise.<*>

#### (async) cancel(subscriptionId, cancelAt) → {Promise.<{tx: *}>}

Cancel (or schedule to be canceled) a subscription.

##### Parameters:

Name | Type | Default | Description
--- | --- | --- | ---
`subscriptionId` | string |  | Subscription ID
`cancelAt` | number | 0 | Unix timestamp for scheduled cancellation, use 0 to turn off a scheduled cancellation.

##### Returns:

Type
  Promise.<{tx: *}>

#### (async) change(subscriptionId, args) → {Promise.<{ref, tx: *, provider, chainId, planId, subscriptionId, consumer: (*)}>}

Change a subscription, such as plan change, the discount or metadata.

##### Parameters:

Name | Type | Description
--- | --- | ---
`subscriptionId` |  | ID of subscription to change
`args` | Object | change function options ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`planId` | number |  | Plan ID for new subscription
`discountCode` | string | <optional> | Discount code of discount to apply to subscription
`discountTokenValidator` | string | <optional> | Discount token validator for token discount to apply to subscription
`name` | string | <optional> | Name for NFT - defaults to auto generated name
`description` | string | <optional> | Description for NFT - defaults to auto generated description
`image` | string | <optional> | URL for NFT image - defaults to provider icon URL if not supplied
`external_url` | string | <optional> | URL for NFT - defaults to provider website URL if not supplied
`attributes` | Array | <optional> | Array of attributes to store with IPFS NFT data
`metadata` | Object | <optional> | Non-encrypted data to associate with subscription

##### Returns:

Type
  Promise.<{ref, tx: *, provider, chainId, planId, subscriptionId, consumer: (*)}>

#### (async) create(args) → {Subscriptions.CreateSubscriptionResult}

Create a new subscription.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | Object | Function arguments ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`provider` | string |  | Address of service provider
`planId` | number |  | Plan ID for new subscription
`ref` | string | <optional> | Optional bytes32 value to associate with subscription
`cancelAt` | number | <optional> | Optional unix timestamp of when to automatically cancel subscription
`name` | string | <optional> | Name for NFT - defaults to auto generated name
`description` | string | <optional> | Description for NFT - defaults to auto generated description
`image` | string | <optional> | URL for NFT image - defaults to provider icon URL if not supplied
`external_url` | string | <optional> | URL for NFT - defaults to provider website URL if not supplied
`attributes` | Array | <optional> | Array of attributes to store with IPFS NFT data
`discountCode` | string | <optional> | Discount code of discount to apply to subscription
`discountTokenValidator` | string | <optional> | Discount token validator for token discount to apply to subscription
`authSig` | AuthSig | <optional> | AuthSig for attaching private data to subscription
`privateData` | Object | <optional> | Private data to attach to subscription
`metadata` | Object | <optional> | Non-encrypted data to associate with subscription

##### Returns:

Type
  Subscriptions.CreateSubscriptionResult

#### (async) estimatedCommitment(address, periodopt)

Get the estimated spend by a consumer on all subscriptions for a specific period

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`address` | string |  |  | Consumer address
`period` | number | <optional> | 1 month | Commitment period

#### (async) get(subscriptionId, optionsopt) → {Promise.<Subscriptions.SubscriptionDetail>}

Get the details of a specific subscription.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`subscriptionId` |  |  |
`options` |  | <optional> | Additional Options ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`decryptPrivateData` | boolean | <optional> | false | Decrypt private data (if present)
`authSig` | AuthSig | <optional> |  | Authsig for private data decryption
`units` | string | <optional> |  | Units of output
`unitOptions` | Object | <optional> | {} | Options passed to unit formatter.

See:
  - The SDK guide for more details on unit formatting at https://docs.cask.fi/developer-docs/javascript-sdk

##### Returns:

Type
  Promise.<Subscriptions.SubscriptionDetail>

#### (async) getConsumerSubscriptionCount(addressopt) → {Promise.<*>}

Get the current number of subscriptions for an address.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`address` |  | <optional> | ethersConnection.address | Provider address or attempts to use the blockchain connection address

Deprecated:
  - use query service

##### Returns:

Type
  Promise.<*>

#### (async) getConsumerSubscriptions(addressopt, limitopt, offsetopt, orderByopt, orderDirectionopt) → {Promise.<*>}

Get a map of subscriptions for a specified address

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`address` |  | <optional> | ethersConnection.address | Provider address or attempts to use the blockchain connection address
`limit` |  | <optional> | 10 | Limit
`offset` |  | <optional> | 0 | Offset
`orderBy` |  | <optional> | createdAt | Order by
`orderDirection` |  | <optional> | asc | Order direction, one of asc or desc

Deprecated:
  - use query service

##### Returns:

Type
  Promise.<*>

#### (async) getProviderSubscriptionCount(addressopt, includeCanceledopt, planId) → {Promise.<*>}

Get the number of subscriptions that are subscribed to a specified service provider.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`address` |  | <optional> | ethersConnection.address | Provider address or attempts to use the blockchain connection address
`includeCanceled` |  | <optional> | false | Also include canceled subscriptions
`planId` |  |  |  | Plan ID

Deprecated:
  - use query service

##### Returns:

Type
  Promise.<*>

#### (async) getProviderSubscriptions(addressopt, limitopt, offsetopt, orderByopt, orderDirectionopt) → {Promise.<*>}

Get a map of subscriptions that are subscribed to a specified service provider.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`address` |  | <optional> | ethersConnection.address | Provider address or attempts to use the blockchain connection address
`limit` |  | <optional> | 10 | Limit
`offset` |  | <optional> | 0 | Offset
`orderBy` |  | <optional> | createdAt | Order by
`orderDirection` |  | <optional> | asc | Order direction, one of asc or desc

Deprecated:
  - use query service

##### Returns:

Type
  Promise.<*>

#### (async) history(subscriptionId, queryoptsopt) → {Promise.<*>}

Get history for a subscription

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`subscriptionId` | string |  | Subscription ID
`queryopts` |  | <optional> | Optional query options ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`limit` |  | <optional> | 10 | Limit
`offset` |  | <optional> | 0 | Offset
`orderBy` |  | <optional> | timestamp | Order by
`orderDirection` |  | <optional> | desc | Order direction, one of asc or desc
`options` |  | <optional> | asc | Optional options to pass to apollo for graphQL

##### Returns:

Type
  Promise.<*>

#### (async) init(args)

Initialize the subscription service.

##### Parameters:

Name | Type | Description
--- | --- | ---
`args` | Object | Function arguments ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`ethersConnection` | EthersConnection | <optional> | EthersConnection instance

#### (async) pause(subscriptionId) → {Promise.<{tx: *}>}

Pause an active subscription.

##### Parameters:

Name | Type | Description
--- | --- | ---
`subscriptionId` | string | Subscription ID

##### Returns:

Type
  Promise.<{tx: *}>

#### (async) resume(subscriptionId) → {Promise.<{tx: *}>}

Resume a paused subscription.

##### Parameters:

Name | Type | Description
--- | --- | ---
`subscriptionId` | string | Subscription ID

##### Returns:

Type
  Promise.<{tx: *}>

### Type Definitions

#### CreateSubscriptionResult

##### Properties:

Name | Type | Description
--- | --- | ---
`tx` | Object | Create Transaction
`consumer` | string | Consumer address
`planId` | number | Plan ID
`ref` | string | Bytes32 data associated with subscription
`chainId` | number | Chain ID that the transacrtion took place on
`subscriptionId` | string | ID of newly created subscription

#### SubscriptionDetail

##### Properties:

Name | Type | Description
--- | --- | ---
`subscriptionId` | string | Subscription ID
`planId` | number | ID of plan that subscription is subscribed to
`status` | number | Subscription status
`createdAt` | number | Unix timestamp of subscription creation time
`renewAt` | number | Unix timestamp of next subscription renewal time
`minTermAt` | number | Unix timestamp of when subscription minimum term is over, 0 if no minimum term
`cancelAt` | number | Unix timestamp of when subscription is scheduled to be canceled
`cid` | string | IPFS cid of subscription data
`discountId` | string | Discount applied to subscription
`plan` | Plan | Plan that subscription is subscribed to
`consumer` | string | Address of current subscription holder
`image` | string | URL to service provider logo
`metadata` | Object | Subscription metadata