Skip to content

Commit

Permalink
Merge pull request #167 from dimitrov-d/main
Browse files Browse the repository at this point in the history 
Add computing API and SDK docs
  • Loading branch information
@dimitrov-d
dimitrov-d authored Apr 2, 2024
2 parents 157c9ef + 4ac05b6 commit 3986910
Show file tree
Hide file tree
Showing 2 changed files with 678 additions and 76 deletions.
207 changes: 131 additions & 76 deletions build/5-apillon-sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ as well as compresses multi step flows into single operations.

## Requirements

- npm 8.4.0 or higher
- node.js 16.17.0 or higher
- npm 10.0.0 or higher
- node.js 20.0.0 or higher
- Apillon API key and secret

## Getting started
Expand All @@ -28,11 +28,11 @@ npm install @apillon/sdk
### Initialization

```ts
import { Hosting } from "@apillon/sdk";
import { Hosting } from '@apillon/sdk';

const hosting = new Hosting({
key: "",
secret: "",
key: '',
secret: '',
});
```

Expand Down Expand Up @@ -80,35 +80,37 @@ import {
DeploymentStatus,
Hosting,
LogLevel,
} from "@apillon/sdk";
import * as fs from "fs";
} from '@apillon/sdk';
import * as fs from 'fs';

const hosting = new Hosting({
key: "yourApiKey",
secret: "yourApiSecret",
logLevel: LogLevel.NONE,
key: 'yourApiKey',
secret: 'yourApiSecret',
logLevel: LogLevel.VERBOSE,
});

// list all websites
await hosting.listWebsites({ orderBy: "createTime" });
await hosting.listWebsites({ orderBy: 'createTime' });

// create an instance of a website via uuid
const webpage1 = hosting.website("uuid");
const webpage1 = hosting.website('uuid');

// gets website information
await webpage1.get();

// Upload files from local folder
await webpage1.uploadFromFolder("./public");
await webpage1.uploadFromFolder('./public');
// Or alternatively, send file buffers as upload parameters
const htmlBuffer = fs.readFileSync("./public/index.html");
await webpage1.uploadFiles([
{
fileName: "index.html",
contentType: "text/html",
content: htmlBuffer,
},
]);
const htmlBuffer = fs.readFileSync('./public/index.html');
await webpage1.uploadFiles(
[
{
fileName: 'index.html',
contentType: 'text/html',
content: htmlBuffer,
},
]
);

// deploys uploaded files to staging environment
await webpage1.deploy(DeployToEnvironment.TO_STAGING);
Expand All @@ -118,7 +120,7 @@ await webpage1.listDeployments();

// gets a specific deployment
const deployment = await webpage1
.deployment("3e0c66ea-317d-4e1f-bcd9-38026c3ea1ee")
.deployment('3e0c66ea-317d-4e1f-bcd9-38026c3ea1ee')
.get();

// checks if deployment was successful
Expand All @@ -136,40 +138,40 @@ For detailed storage SDK method, class and property documentation visit [SDK sto
### Usage example

```ts
import { Storage, LogLevel, FileStatus } from "@apillon/sdk";
import * as fs from "fs";
import { Storage, LogLevel, FileStatus } from '@apillon/sdk';
import * as fs from 'fs';

const storage = new Storage({
key: "yourApiKey",
secret: "yourApiSecret",
logLevel: LogLevel.NONE,
key: 'yourApiKey',
secret: 'yourApiSecret',
logLevel: LogLevel.VERBOSE,
});

// list buckets
await storage.listBuckets({ limit: 5 });

// create and instance of a bucket directly through uuid
const bucket = storage.bucket("uuid");
const bucket = storage.bucket('uuid');

// Upload files from local folder
await bucket.uploadFromFolder("./my-folder/files/");
await bucket.uploadFromFolder('./my-folder/files/');
// Or alternatively, send file buffers as upload parameters
const pdfBuffer = fs.readFileSync("./my-folder/files/document.pdf");
const pdfBuffer = fs.readFileSync('./my-folder/files/document.pdf');
await bucket.uploadFiles(
[
{
fileName: "document.pdf",
contentType: "application/pdf",
fileName: 'document.pdf',
contentType: 'application/pdf',
content: pdfBuffer,
},
],
// Upload the files in a new subdirectory in the bucket instead of in the root of the bucket
{ wrapWithDirectory: true, directoryPath: "main/documents" }
{ wrapWithDirectory: true, directoryPath: 'main/documents' }
);

// list objects (files, folders) in a bucket
await bucket.listObjects({
directoryUuid: "eaff2672-3012-46fb-9278-5efacc6cb616",
directoryUuid: 'eaff2672-3012-46fb-9278-5efacc6cb616',
markedForDeletion: false,
limit: 5,
});
Expand All @@ -178,12 +180,12 @@ await bucket.listObjects({
await bucket.listFiles({ fileStatus: FileStatus.UPLOADED });

// gets a specific file in a bucket directly through uuid
const file = await bucket.file("2195521d-15cc-4f6e-abf2-13866f9c6e03").get();
const file = await bucket.file('2195521d-15cc-4f6e-abf2-13866f9c6e03').get();

// deletes a file via uuid
await bucket.file("2195521d-15cc-4f6e-abf2-13866f9c6e03").delete();
await bucket.file('2195521d-15cc-4f6e-abf2-13866f9c6e03').delete();
// deletes a directory via uuid
await bucket.directory("eddc52cf-92d2-436e-b6de-42d7cad621c3").delete();
await bucket.directory('eddc52cf-92d2-436e-b6de-42d7cad621c3').delete();
```

### IPNS methods
Expand All @@ -193,28 +195,28 @@ The Storage module additionally contains methods for manipulating IPNS records f
For detailed IPNS SDK method, class and property documentation visit [SDK IPNS docs](https://sdk-docs.apillon.io/classes/Ipns.html).

```ts
import { Storage, LogLevel } from "@apillon/sdk";
import { Storage, LogLevel } from '@apillon/sdk';

const storage = new Storage({
key: "yourApiKey",
secret: "yourApiSecret",
logLevel: LogLevel.NONE,
key: 'yourApiKey',
secret: 'yourApiSecret',
logLevel: LogLevel.VERBOSE,
});

// create and instance of a bucket directly through uuid
const bucket = storage.bucket("uuid");
const bucket = storage.bucket('uuid');
// list all existing IPNS records
const ipnsNames = await bucket.listIpnsNames({ ipnsName: "Images IPNS" });
const ipnsNames = await bucket.listIpnsNames({ ipnsName: 'Images IPNS' });
// create a new IPNS record
const newIpns = await bucket.createIpns({
name: "Music IPNS",
description: "IPNS for my music files",
cid: "QmS5NL2Rc6SCjFx7pvZHdTD8WGWjDt25WQskC7DsNKAatW",
name: 'Music IPNS',
description: 'IPNS for my music files',
cid: 'QmS5NL2Rc6SCjFx7pvZHdTD8WGWjDt25WQskC7DsNKAatW',
});
// Get an IPNS record's details by UUID
const ipns = await bucket.ipns("ipns_uuid").get();
const ipns = await bucket.ipns('ipns_uuid').get();
// Publish an IPNS record to point to a given CID
await ipns.publish("QmajaeC15ZpcnjBpX4ARRBU127fpcZ2svYEfEBhFRkRZbN");
await ipns.publish('QmajaeC15ZpcnjBpX4ARRBU127fpcZ2svYEfEBhFRkRZbN');
// delete an IPNS record from the bucket
await ipns.delete();
```
Expand All @@ -225,9 +227,9 @@ NFT module encapsulates functionalities for NFT service available on Apillon das

For detailed NFT SDK method, class and property documentation visit [SDK NFT docs](https://sdk-docs.apillon.io/classes/Nft.html).

::: warning
When you transfer ownership of the collection to another account Apillon will lose the ability to perform actions in your name (mint, burn, etc.). Before you transfer ownership make sure you do not need those functionalities via Apillon anymore.
:::
> **Warning**
> When you transfer ownership of the collection to another account Apillon will lose the ability to perform actions in your name (mint, burn, etc.). Before you transfer ownership make sure you do not need those functionalities via Apillon anymore.

### Usage example

Expand All @@ -238,27 +240,28 @@ import {
LogLevel,
Nft,
TransactionStatus,
} from "@apillon/sdk";
} from '@apillon/sdk';

const nft = new Nft({
key: "yourApiKey",
secret: "yourApiSecret",
logLevel: LogLevel.NONE,
key: 'yourApiKey',
secret: 'yourApiSecret',
logLevel: LogLevel.VERBOSE,
});

// create a new collection
const collection1 = await nft.create({
collectionType: CollectionType.GENERIC,
chain: EvmChain.MOONBEAM,
name: "SpaceExplorers",
symbol: "SE",
description: "A collection of unique space exploration NFTs.",
baseUri: "https://moonbeamnfts.com/collections/spaceexplorers/",
baseExtension: "json",
name: 'SpaceExplorers',
symbol: 'SE',
description: 'A collection of unique space exploration NFTs.',
baseUri: 'https://moonbeamnfts.com/collections/spaceexplorers/',
baseExtension: 'json',
// If you omit the maxSupply parameter, the max supply will be unlimited
maxSupply: 1000,
isRevokable: false,
isSoulbound: false,
royaltiesAddress: "0x1234567890abcdef",
royaltiesAddress: '0x1234567890abcdef',
royaltiesFees: 5,
drop: true,
dropStart: 1679875200,
Expand All @@ -268,23 +271,23 @@ const collection1 = await nft.create({

// check if collection is deployed - available on chain
if (collection1.collectionStatus == CollectionStatus.DEPLOYED) {
console.log("Collection deployed: ", collection1.transactionHash);
console.log('Collection deployed: ', collection1.transactionHash);
}

// search through collections
await nft.listCollections({ search: "My NFT" });
await nft.listCollections({ search: 'My NFT' });

// create and instance of collection directly through uuid
const collection = await nft.collection("uuid").get();
const collection = await nft.collection('uuid').get();

// mint a new nft in the collection
await collection.mint("0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD", 1);
await collection.mint('0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD', 1);

// nest mint a new nft if collection type is NESTABLE
await collection.nestMint(collection.uuid, 1, 1);

// burn/destroy a specific NFT by its ID if collection is set as revokable
await collection.burn("1");
await collection.burn('1');

// list confirmed transactions on a collection
await collection.listTransactions({
Expand All @@ -295,10 +298,11 @@ await collection.listTransactions({
// NOTE that this will disable the ability to mint/burn etc. from the SDK/API since only the owner
// has this ability
await collection.transferOwnership(
"0x5BA8B0c24bA5307b67E619ad500a635204F73bF1"
'0x5BA8B0c24bA5307b67E619ad500a635204F73bF1'
);
```


## Identity

Identity module encapsulates functionalities for validating EVM and Polkadot wallet signatures, as well as fetching Polkadot Identity data for any wallet.
Expand All @@ -308,14 +312,14 @@ For detailed hosting SDK method, class and property documentation visit [SDK ide
### Usage example

```ts
import { Identity } from "./modules/identity/identity";
import { LogLevel } from "./types/apillon";
import { Identity } from './modules/identity/identity';
import { LogLevel } from './types/apillon';

// Note: for signature-related methods API config is not required
const identity = new Identity({
key: "yourApiKey",
secret: "yourApiSecret",
logLevel: LogLevel.NONE,
key: 'yourApiKey',
secret: 'yourApiSecret',
logLevel: LogLevel.VERBOSE,
});

// obtain on-chain identity data for a Polkadot wallet
Expand All @@ -324,15 +328,15 @@ const { polkadot, subsocial } = await identity.getWalletIdentity(address);
async function validateEvmWalletSignature() {
// generate a custom message to be signed by the user's wallet
const { message, timestamp } = await identity.generateSigningMessage(
"Custom display message here"
'Custom display message here',
);

// alternatively, you can generate you own signing message with timestamp like this:
// const timestamp = new Date().getTime();
// const message = 'Message from my Dapp';
// const signingMessage = `${message}\n${timestamp}`;

const walletAddress = "0xa79bg13g2...";
const walletAddress = '0xa79bg13g2...';

// validate an EVM wallet's signature for a given message
const { isValid, address } = await identity.validateEvmWalletSignature({
Expand All @@ -356,16 +360,67 @@ async function validatePolkadotWalletSignature() {
// If you wish to generate the message yourself and validate the timestamp,
// use a signing message as shown below:
const timestamp = new Date().getTime();
const message = "Message from my Dapp";
const message = 'Message from my Dapp';
const signingMessage = `${message}\n${timestamp}`;

// validate a Polkadot wallet's signature for a given signing message
const { isValid } = await identity.validatePolkadotWalletSignature({
message: signingMessage,
signature, // signature obtained from the user's wallet by the client app
walletAddress: "5HqHQDGcHqS...",
walletAddress: '5HqHQDGcHqS...',
timestamp,
signatureValidityMinutes: 5,
});
}

```
## Computing

The Computing module provides functionalities for managing computing contracts, including creating contracts, listing contracts, and interacting with specific contracts for operations like encryption and ownership transfer.

### Usage example

```ts
const computing = new Computing({
key: 'yourApiKey',
secret: 'yourApiSecret',
});

// List all computing contracts
const contracts = await computing.listContracts();
console.log(contracts);

// Create a new computing contract
const newContract = await computing.createContract({
name: 'New Contract',
description: 'Description of the new contract',
nftContractAddress: '0xabc...',
nftChainRpcUrl: ChainRpcUrl.ASTAR,
});

// Interact with a specific computing contract
const contract = computing.contract(newContract.uuid);

// Get details of the contract
const contractDetails = await contract.get();
console.log(contractDetails);

// List transactions of the contract
const transactions = await contract.listTransactions();
console.log(transactions);

// Encrypt a file and upload it to the associated bucket
const encryptionResult = await contract.encryptFile({
fileName: 'example.txt',
content: Buffer.from('Hello, world!'),
nftId: 1, // NFT ID used for decryption authentication
});
console.log(encryptionResult);

// Transfer ownership of the contract
const newOwnerAddress = '0xNewOwnerAddress';
const successResult = await contract.transferOwnership(newOwnerAddress);
console.log(
`Ownership transfer was ${successResult ? 'successful' : 'unsuccessful'}.`,
);
```
Loading

0 comments on commit 3986910

Please sign in to comment.