diff --git a/documentation/versioned_docs/version-v0.15/modules/authentication/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/authentication/sdk_usage.mdx new file mode 100644 index 0000000..0ebce49 --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/authentication/sdk_usage.mdx @@ -0,0 +1,66 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +## User Creation + +You may easily create users (utilizing the [Local Authentication](./strategies#local) strategy) through the SDK.
+The `verify` boolean field specifies whether the newly created user **should verify themselves**. + +:::caution +User authentication requires that the Email module is available and [configured](../email/config).
+The Authentication module's Local Authentication strategy should also enable email verification. +::: + +[//]: # (TODO: Update verify naming) + +```ts +await grpcSdk.authentication.userCreate({ + email: "somemail@example.com", + password : "P@$$w0rd", + verify: true, +}); +``` + +## User Login + +You may retrieve an access/refresh token pair for your users through the SDK.
+Specifying a [security client](../router/security.mdx) id for your login request is required. + +[//]: # (TODO: Update this once security clients are optional in gRPC) + +```ts title="Request" +await grpcSdk.authentication.userLogin({ + userId: "someuserid", + clientId: "someclientid" +}); +``` + +```ts title="Response" +{ + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyNDJmMWJiMTBhMDk5MDE4Mjc3MzhmZSIsImlhdCI6MTY0ODU1NDUyNywiZXhwIjoxNzM0OTU0NTI3fQ.Fjqa7ORBBF2giwG7OgiWr2HMgHDL7R6ddFq2E730Djc", + "refreshToken": "BsKhe3ARhL/FfDfK1REphKkkqQaxRCj/LvvRHOg5wCXCBaUSOwafRHyFYIttaORY/NmHS7NAuT6+knBQegVOwQ==" +} +``` + +## User Deletion + +```ts title="Request" +await grpcSdk.authentication.userDelete({ + userId: "someuserid" +}); +``` + +## Changing Passwords + +You may update the passwords for any users utilizing [Local Authentication](./strategies#local). + +```ts title="Request" +await grpcSdk.authentication.changePass({ + email: "somemail@example.com", + password: "newP@$$w0rd" +}); +``` diff --git a/documentation/versioned_docs/version-v0.15/modules/chat/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/chat/sdk_usage.mdx new file mode 100644 index 0000000..e8a05b8 --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/chat/sdk_usage.mdx @@ -0,0 +1,57 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +## Room Creation + +Let's begin by creating a room. All you need is: +- A participant array which include the participants user ids. +- A room name. + +```ts title="Request" +await grpcSdk.chat.createRoom({ + name: "roomName", + participants: ["userId1", "userId2"], +}); +``` +```ts title="Response" +{ + room: { + Id: "roomId", + name: "roomName", + participants: ["userId1", "userId2"] + } +} +``` + +## Room Deletion + +```ts title="Request" +await grpcSdk.chat.deleteRoom({ + id: "roomId", +}); +``` +```ts title="Response" +{ + room: { + Id: "roomId", + name: "roomName", + participants: ["userId1", "userId2"] + } +} +``` + +## Sending Messages + +Before sending a message to a group, make sure the user you're sending it as is already a member of the group. + +```ts title="Request" +await grpcSdk.chat.sendMessage({ + userId: "userId", + roomId: "roomId", + message: "Hello Conduit users!" +}); +``` diff --git a/documentation/versioned_docs/version-v0.15/modules/database/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/database/sdk_usage.mdx new file mode 100644 index 0000000..31c6e9c --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/database/sdk_usage.mdx @@ -0,0 +1,274 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +Since the database is up, its SDK comes up with a bunch of operations you could use. +In order to explain the functionality of the database SDK, we're going to extend +the [movie tutorial](./tutorials/cinema_ticket_booking).
+To start operating on schemas, you need to create one first. Let's create a movie schema using the SDK. + +## Schema Creation + +Create schema from adapter accepts a JSON schema as an argument, and it stores into the database. +Additional arguments are required such as: +- Schema name +- [Schema fields](./sdk_usage#schema-fields) +- [Schema model options](./sdk_usage#model-options) +- Owner module name // module that owns the module +- Collection name ( name of the collection) + +### Schema fields +Schema fields represent the whole schema. Each field may have: + +Name | Type | Description | +| ---- | ---- | ----------- | +| `type` | TYPE | Could be TYPE.(String,Number,Boolean etc.)| +| `required` | boolean | Indicates whether a field is required. | +| `unique` | boolean | Indicates whether a field is unique. | +| `select` | boolean | Indicates whether a field could be retreived from a query. | +| `description` | string | Description of the field, | +| `default` | any | Default value of the field. | +| `enum` | enum values | When a field has enum values. | + +Assume that we want to create a movie schema. A movie may have **title** , **genre**, **duration**, **director** , **description** and surely an **_id** field. +So a possible schema could be this: + +```jsx title="Movie schema" +enum MoviesGenreEnum { + THRILLER = "THRILLER", + COMEDY = "COMEDY", + ADVENTURE ="ADVENTURE", + SCIENCE_FICTION = "SCIFI" +}; + +const schema = { + _id: TYPE.ObjectId, + name: { + type: TYPE.String, + unique: true, + required: true, + }, + director: { + type: TYPE.String, + required: true, + }, + duration: { + type: TYPE.Number + }, + genre: { + type: TYPE.String, + enum: Object.values(MoviesGenreEnum), + required: true, + }, + description: { + type: TYPE.String, + required: false, + unique: false, + }, + releaseDate: TYPE.Date, + createdAt: TYPE.Date, + updatedAt: TYPE.Date, +} +``` +### Model Options + +There is another argument that createSchemaFromAdapter() needs, and it is called modelOptions. +Model options are objects that are stored in the database and contain some information about our schema. + +Name | Type | Description | +| ---- | ---- | ----------- | +| `type` | TYPE | Could be TYPE.(String,Number,Boolean etc.)| +| `conduit.permissions` | object | Schema permissions | +| `conduit.persmissions.extendable` | boolean | Indicates if a schema could be extend after its creation. | +| `conduit.permissions.canCreate` | boolean | Indicates if a module can create documents of that schema. | +| `conduit.permissions.canModify` | boolean | Indicates if a module can modify documents of that schema. | +| `conduit.permissions.canDelete` | boolean | Indicates if a module can delete of that schema. | + +A modelOptions object could be this: + +```jsx title="Model options object" +const modelOptions = { + timestamps: true, + conduit: { + permissions: { + extendable: true, + canCreate: false, + canModify: 'ExtensionOnly', + canDelete: false, + }, + }, +} as const; +``` + +## Schema Creation + +```ts title="Request" +await grpcSdk.database.createSchemaFromAdapter({ + name: "Movies", + fields: schema, + modelOptions: modelOptions, + collectionName: "", // could be 'Movies' also +}); +``` + +## Schema Retrieval + +```ts title="Request" +await grpcSdk.database.getSchemas({}); +``` + +## Schema Deletion + +Deleting schemas could also be done by calling the SDK's deleteSchema() function. All you need is Schema's name. +Remember that conduit allows you to delete the schema's created documents as well. + +```ts title="Request" +await grpcSdk.database.deleteSchema({ + name: "Movies", + deleteData: true // could be also false +}); +``` + + +## Extending Schemas + +Most Conduit modules need to register schemas and perform database queries for their data.
+These schemas are usually limited to the functionality that's required for their owner's internal operations. + +The Authentication module, for instance, registers a plain `User` schema, containing just enough descriptor fields for its authentication strategies.
+The `User` schema doesn't make any assumptions in regard to how user-facing apps would account for additional user-related information. + +Suppose your use case requires that you keep track of a user's first and last names.
+Traditionally, you would register your own `UserInfo` schema, including these fields as well as a relation field to the `User` entry they reference.
+Instead, Conduit lets you extend the main `User` schema, appending the fields you deem necessary, +as long as they are not part of the schema's base fields or otherwise already provided through another modules' extension on the same schema. + +```ts title="Request" +await grpcSdk.database.setSchemaExtension({ + schemaName: "Movies", + extOwner: "yourModule", + extFields: { + firstName: { + type: "String", + required: "true", + }, + lastName: { + type: "String", + required: "true", + }, + }, +}); +``` + +Now the User schema includes this new field called **recoverEmail**. + +## Database Operations + +Conduit models provide several static helper functions for CRUD operations.
+Queries are structured Mongoose-like. To see Conduit's query language click [here](./operators). + +### Document Retrieval + +Suppose we wish to find a record with a specific id. + +```ts title="Request" +await grpcSdk.database + .findOne("Movies",{ _id: "someMovieId" }); +``` + +### Multi-Document Retrieval + +Suppose we want to fetch all Movies that have a duration greater than 1 hour. + +```ts title="Request" +await grpcSdk.database + .findMany("Movies", { duration: { $gt: 60 } }); +``` + +### Document Creation + +Create operation is very simple. Just invoke the **create()** function through database sdk and fill the +necessary fields for document creation. + +```ts title="Request" +await grpcSdk.database + .create("Movies",{ + title: "The Hobbit", + duration: 165, + genre: "scifi", + description: "Tolkien rocks", + director: "Peter Jackson", + releaseDate: "13/12/2012" + }); +``` + +### Multi-Document Creation + +```ts title="Request" +await grpcSdk.database.createMany("User", + [ + { + title: "The Hobbit", + duration: 165, + genre: "scifi", + description: "Tolkien rocks", + director: "Peter Jackson", + releaseDate: "13/12/2012" + }, + { + title: "The Spiderman", + duration: 200, + genre: "scifi", + description: "Marvel rocks", + director: "Sam Raimi", + releaseDate: "29/04/2002" + }, + ] +); +``` + + +### Multi-Document Updates + +We can use `updateMany()`to update multiple documents given some optional constraints.
+Suppose we wish to discontinue some movies from an online streaming service. + +```ts title="Request" +const discontinuedMovies = [movieId2, movieId2,movieId3]; +await grpcSdk.database + .updaeteMany("Movies",{ _id: { $in: discontinuedMovies } }, { discontinued: true }); +``` + +### Document Deletion + +The only thing we need is the document ID we want to delete. + +```ts title="Request" +await grpcSdk.database + .deleteOne("Movies",{ _id : id }); +``` + +### Multi-Document Deletion + +Like updateMany we can use `deleteMany` to delete documents given some constraints. + +```ts title="Request" +const idArray = [movieid2, movieid2, movieid3]; +await grpcSdk.database + .deleteMany("Movies",{ _id :{ $in: idArray } }); +``` + +### Document Count + +Sometimes we only need to count how many documents exist with specific features. +For example, if we want to count how many movies are suitable only for. +**countDocuments()** should be used.
+An alternative but more complicated way of doing it is to use **findMany()** and calculate the length of the returned array. + +```ts title="Request" +await grpcSdk.database + .countDocuments("Movies",{ genre: "SCIFI" }); +``` diff --git a/documentation/versioned_docs/version-v0.15/modules/email/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/email/sdk_usage.mdx new file mode 100644 index 0000000..bc5c2ce --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/email/sdk_usage.mdx @@ -0,0 +1,47 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +Using the email module SDK, you can send emails using templates. The only requirement is that the template should be registered in the database. +Conduit provides a template mechanism. Templates can be created with or without variables. +To create a template with variables, do it by using [handlebars](https://handlebarsjs.com/guide/). + +## Templates + +### Template registration +To create a template in to the database we need to set four fields. +- **Name**: The name of the template +- **Subject**: The subject of the email template +- **Body**: The body of the template. Could also be html document. +- **Variables**: An array of strings which contain the names of the template variables. +```ts title="Request" +await grpcSdk.email.registerTemplate({ + name: 'template_name', + subject: 'subject', + body: '

Hello, {{user}}. I hope you are doing well.

', + variables: ['user'] +}) +``` + +## Sending an email with templates +Sending emails with templates requires you to configure each template variable with a specific value. +For instance if you want the **user** variable to be rendered to "Conduit" you have to specify it. +```ts title="Request" +await grpcSdk.email.sendEmail('template_name',{ + email : 'mail@example.com', + sender: 'sendermail@example.com', + variables: { + user : 'Conduit', + } +}) +``` + +This email will be rendered into this: +``` +

Helo, Conduit, I hope you are doing well

+``` + +As you can see above, the ***User*** variable is replaced by the value we gave. \ No newline at end of file diff --git a/documentation/versioned_docs/version-v0.15/modules/push-notifications/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/push-notifications/sdk_usage.mdx new file mode 100644 index 0000000..e9cccaa --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/push-notifications/sdk_usage.mdx @@ -0,0 +1,88 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +Depending on the configured provider, Conduit SDK provides push notification utilities.For now, only Firebase and OneSignal providers are implemented.
+As it was mentioned before, push notifications are sent to applications that are related to users. +In fact, a user is related to a notification token, and a token is related to an application. +A notification token is a unique identifier generated for a user, and thus for an application as well. +For instance, the Firebase messaging system provides tokens for sending push notifications.
+Conduit represents these tokens as objects, which include three subfields. + +In detail: + +```jsx title="Notification Token Object" +{ + _id: ObjectId, + userId: ObjectId, //user's Id related with this token, + token: string, // actual token related with the application + platform: string, // application platform +} +``` + + +## Set notification token + +A reasonable question is "How is a notification token related to a user?" Conduit has the answer for you. +Using the **setNotificationToken()** SDK function, you can "relate" a token to a user. + + +```ts title="Request" +await grpcSdk.pushNotifications.setNotificationToken({ + token: "applicationtoken", + platform: "WEB", // could be also ANDROID,IOS,MACOS,LINUX,CLI,IPADOS + userId: "someuserid", // user related with this token +}) +``` + +## Get notification token + +Getting a user's notification token will be an easy process. Just call getNotificationTokens() function. +```ts title="Request" +await grpcSdk.pushNotifications.getNotificationTokens({ + userId: "someuserid", // user related with this token +}) +``` +Response will include an array of Notification Token Object + +```jsx title="Response" +tokens: [{ + _id: ObjectId, + userId: ObjectId, //user's Id related with this token, + token: string, // actual token related with the application + platform: string, // application platform +}] +``` + +## Send Notification + +Congratulations! You are now ready to send push notifications. + +```ts title="Request" +await grpcSdk.pushNotifications.sendNotification({ + sendTo: "diresuemos", + title: "Hello 666.I have a message for you.", + body: "Conduit will send you to heaven.Try it." +}) +``` +Appropriate message will be returned to you if everything went well. +```jsx title="Response" +response: { + message: "Ok" +} +``` + +## Send many notifications + +There is a "plus" function for sending push notifications to many users concurrently. +```ts title="Request" +await grpcSdk.pushNotifications.sendToManyDevices({ + sendTo: ["diresuemos","somueserid2","someuserid3"], + title: "Hello 666.I have a message for you.", + body: "Conduit will send you to heaven.Try it." +}) + +``` \ No newline at end of file diff --git a/documentation/versioned_docs/version-v0.15/modules/sms/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/sms/sdk_usage.mdx new file mode 100644 index 0000000..bf158e6 --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/sms/sdk_usage.mdx @@ -0,0 +1,55 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +Underworld has to know about Conduit Platform. Just use sms module to do it. + +:::caution +Sms module has to be configured with the proper provider. +::: + +## Send Sms + +```ts title="Request" +await grpcSdk.sms.sendSms({ + to: "+6666666666", + message: "Hello. Conduit rocks!" +}) +``` + +## Verify via sms + +Conduit provides a verification mechanism by sending SMS. You can verify everything in two steps.
+The **sendVerificationCode** function will be used to send a verification code to the user in the first step. + +```ts title="Request" +await grpcSdk.sms.sendVerificationCode({ + to: "+6666666666", +}) +``` + +```ts title="Response" +{ + "verificationSid": string +} +``` + +A verificationSid will be returned to you. Also, a code will be sent to the user. +To proceed to the next and final step you have to use these to make the verification + +```ts title="Request" +await grpcSdk.sms.verify({ + verificationSid : "someverificationsid", + code: "verificationcode" +}) +``` + +```ts title="Response" +{ + "verfied": boolean, +} +``` +If verification process went well then the returned value will be true. \ No newline at end of file diff --git a/documentation/versioned_docs/version-v0.15/modules/storage/sdk_usage.mdx b/documentation/versioned_docs/version-v0.15/modules/storage/sdk_usage.mdx new file mode 100644 index 0000000..090476b --- /dev/null +++ b/documentation/versioned_docs/version-v0.15/modules/storage/sdk_usage.mdx @@ -0,0 +1,46 @@ +--- +sidebar_label: 'SDK Usage' +sidebar_position: 100 +--- + +# SDK Usage + +Using Conduit, it is simple to interact with storage systems. Storage SDK provides you with the ability +of creating, updating, and getting files since the storage provider is configured. You can also fetch the +data from an already existing file. + +## Create + +```ts title="Request" +await grpcSdk.storage.createFile(name,mimeType,data,folder,isPublic) +``` + +```ts title="Response" +{ + "id": "fileid", + "url": "fileurl", + "name": "fileName" +} +``` +## Get a file + +```ts title="Request" +await grpcSdk.storage.getFile(fileId) +``` + +## Get file's data + +```ts title="Request" +await grpcSdk.storage.getFileData(fileId) +``` + +```ts title="Response" +{ + "data": "stringifiedFileData" +} +``` +## Update a file + +```ts title="Request" +await grpcSdk.storage.updateFile(name,mimeType,data,folder,isPublic) +``` \ No newline at end of file