From bfc3c7e7c9073a3ee8f8b13b95b93c9c6d7e7ae1 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Thu, 4 Jul 2024 03:18:52 +0000 Subject: [PATCH 1/6] Initial email settings schemas --- docs/objects/setings/EmailSettings.yaml | 77 +++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/objects/setings/EmailSettings.yaml diff --git a/docs/objects/setings/EmailSettings.yaml b/docs/objects/setings/EmailSettings.yaml new file mode 100644 index 00000000..efa2a5d7 --- /dev/null +++ b/docs/objects/setings/EmailSettings.yaml @@ -0,0 +1,77 @@ +components: + schemas: + EreaderDeviceObject: + type: object + description: An e-reader device configured to receive EPUB through e-mail. + properties: + name: + type: string + description: The name of the e-reader device. + email: + type: string + description: The email address associated with the e-reader device. + availabilityOption: + type: string + description: The availability option for the device. + enum: ['adminOrUp', 'userOrUp', 'guestOrUp', 'specificUsers'] + users: + type: array + description: List of specific users allowed to access the device. + items: + type: string + required: + - name + - email + - availabilityOption + EmailSettings: + type: object + description: The email settings configuration for the server. This includes the credentials to send e-books and an array of e-reader devices. + properties: + id: + type: string + description: The unique identifier for the email settings. Currently this is always `email-settings` + example: email-settings + host: + type: string + description: The SMTP host address. + nullable: true + port: + type: integer + format: int32 + description: The port number for the SMTP server. + example: 465 + secure: + type: boolean + description: Indicates if the connection should use SSL/TLS. + example: true + rejectUnauthorized: + type: boolean + description: Indicates if unauthorized SSL/TLS certificates should be rejected. + example: true + user: + type: string + description: The username for SMTP authentication. + nullable: true + pass: + type: string + description: The password for SMTP authentication. + nullable: true + testAddress: + type: string + description: The test email address used for sending test emails. + nullable: true + fromAddress: + type: string + description: The default "from" email address for outgoing emails. + nullable: true + ereaderDevices: + type: array + description: List of configured e-reader devices. + items: + $ref: '#/components/schemas/EreaderDeviceObject' + required: + - id + - port + - secure + - rejectUnauthorized + - ereaderDevices From 046bf52d883b6c98fcfd5236421280db3c04a1f6 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Thu, 4 Jul 2024 03:36:01 +0000 Subject: [PATCH 2/6] Initial EmailController paths --- docs/controllers/EmailController.yaml | 95 +++++++++++++++++++++++++ docs/objects/setings/EmailSettings.yaml | 7 +- 2 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 docs/controllers/EmailController.yaml diff --git a/docs/controllers/EmailController.yaml b/docs/controllers/EmailController.yaml new file mode 100644 index 00000000..e0025c14 --- /dev/null +++ b/docs/controllers/EmailController.yaml @@ -0,0 +1,95 @@ +components: + schemas: + emailSettings: + type: string + description: The field to sort by from the request. + example: 'media.metadata.title' + responses: + email200: + description: Successful response - Email + content: + application/json: + schema: + $ref: '../objects/settings/EmailSettings.yaml#/components/schemas/EmailSettings' + ereader200: + description: Successful response - Ereader + content: + application/json: + schema: + type: object + properties: + ereaderDevices: + type: array + items: + $ref: '../objects/settings/EmailSettings.yaml#/components/schemas/EreaderDeviceObject' +paths: + /api/emails: + get: + description: Get email settings + operationId: getEmailSettings + responses: + 200: + $ref: '#/components/responses/email200' + patch: + summary: Update email settings + operationId: updateEmailSettings + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/EmailSettings' + responses: + 200: + $ref: '#/components/responses/email200' + /api/emails/test: + post: + summary: Send test email + operationId: sendTestEmail + responses: + 200: + description: Successful response + /api/emails/ereader-devices: + post: + summary: Update e-reader devices + operationId: updateEReaderDevices + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + ereaderDevices: + type: array + items: + $ref: '#/components/schemas/EreaderDeviceObject' + responses: + 200: + $ref: '#/components/responses/ereader200' + 400: + description: Invalid payload + /api/emails/send-ebook-to-device: + post: + summary: Send ebook to device + operationId: sendEBookToDevice + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + libraryItemId: + $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId' + deviceName: + $ref: '../objects/schemas/EmailSettings.yaml#/components/schemas/ereaderName' + responses: + 200: + description: Successful response + 400: + description: Invalid request + 403: + description: Forbidden + 404: + description: Not found diff --git a/docs/objects/setings/EmailSettings.yaml b/docs/objects/setings/EmailSettings.yaml index efa2a5d7..acce79c7 100644 --- a/docs/objects/setings/EmailSettings.yaml +++ b/docs/objects/setings/EmailSettings.yaml @@ -1,12 +1,14 @@ components: schemas: + ereaderName: + type: string + description: The name of the e-reader device. EreaderDeviceObject: type: object description: An e-reader device configured to receive EPUB through e-mail. properties: name: - type: string - description: The name of the e-reader device. + $ref: '#/components/schemas/ereaderName' email: type: string description: The email address associated with the e-reader device. @@ -73,5 +75,4 @@ components: - id - port - secure - - rejectUnauthorized - ereaderDevices From e60a91379a8adacdd75d2f2958619d0a1e20dd31 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Thu, 4 Jul 2024 03:40:17 +0000 Subject: [PATCH 3/6] Rename folder --- docs/objects/{setings => settings}/EmailSettings.yaml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/objects/{setings => settings}/EmailSettings.yaml (100%) diff --git a/docs/objects/setings/EmailSettings.yaml b/docs/objects/settings/EmailSettings.yaml similarity index 100% rename from docs/objects/setings/EmailSettings.yaml rename to docs/objects/settings/EmailSettings.yaml From b8e17de8b4ed19658093b08da8e96843f9d61f24 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Thu, 4 Jul 2024 03:45:04 +0000 Subject: [PATCH 4/6] Add: EmailController to `root.yaml` --- docs/controllers/EmailController.yaml | 14 ++++++++++++-- docs/root.yaml | 10 ++++++++++ 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/controllers/EmailController.yaml b/docs/controllers/EmailController.yaml index e0025c14..3a7d990e 100644 --- a/docs/controllers/EmailController.yaml +++ b/docs/controllers/EmailController.yaml @@ -27,12 +27,16 @@ paths: get: description: Get email settings operationId: getEmailSettings + tags: + - Email responses: 200: $ref: '#/components/responses/email200' patch: summary: Update email settings operationId: updateEmailSettings + tags: + - Email requestBody: required: true content: @@ -46,6 +50,8 @@ paths: post: summary: Send test email operationId: sendTestEmail + tags: + - Email responses: 200: description: Successful response @@ -53,6 +59,8 @@ paths: post: summary: Update e-reader devices operationId: updateEReaderDevices + tags: + - Email requestBody: required: true content: @@ -63,7 +71,7 @@ paths: ereaderDevices: type: array items: - $ref: '#/components/schemas/EreaderDeviceObject' + $ref: '../objects/settings/EmailSettings.yaml#/components/schemas/EreaderDeviceObject' responses: 200: $ref: '#/components/responses/ereader200' @@ -73,6 +81,8 @@ paths: post: summary: Send ebook to device operationId: sendEBookToDevice + tags: + - Email requestBody: required: true content: @@ -83,7 +93,7 @@ paths: libraryItemId: $ref: '../objects/LibraryItem.yaml#/components/schemas/libraryItemId' deviceName: - $ref: '../objects/schemas/EmailSettings.yaml#/components/schemas/ereaderName' + $ref: '../objects/settings/EmailSettings.yaml#/components/schemas/ereaderName' responses: 200: description: Successful response diff --git a/docs/root.yaml b/docs/root.yaml index ee9d7b9c..e3caedaa 100644 --- a/docs/root.yaml +++ b/docs/root.yaml @@ -21,6 +21,14 @@ paths: $ref: './controllers/AuthorController.yaml#/paths/~1api~1authors~1{id}~1image' /api/authors/{id}/match: $ref: './controllers/AuthorController.yaml#/paths/~1api~1authors~1{id}~1match' + /api/emails: + $ref: './controllers/EmailController.yaml#/paths/~1api~1emails' + /api/emails/test: + $ref: './controllers/EmailController.yaml#/paths/~1api~1emails~1test' + /api/emails/ereader-devices: + $ref: './controllers/EmailController.yaml#/paths/~1api~1emails~1ereader-devices' + /api/emails/send-ebook-to-device: + $ref: './controllers/EmailController.yaml#/paths/~1api~1emails~1send-ebook-to-device' /api/libraries: $ref: './controllers/LibraryController.yaml#/paths/~1api~1libraries' /api/libraries/{id}: @@ -54,5 +62,7 @@ tags: description: Library endpoints - name: Series description: Series endpoints + - name: Email + description: Email endpoints - name: Notification description: Notifications endpoints From 6d14ed8a72237835987ea0d23941bbdd0693f049 Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Thu, 4 Jul 2024 03:48:22 +0000 Subject: [PATCH 5/6] Update: bundled spec --- docs/openapi.json | 276 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 269 insertions(+), 7 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 48274bb3..826bf84b 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -29,6 +29,10 @@ "name": "Series", "description": "Series endpoints" }, + { + "name": "Email", + "description": "Email endpoints" + }, { "name": "Notification", "description": "Notifications endpoints" @@ -416,6 +420,132 @@ } } }, + "/api/emails": { + "get": { + "description": "Get email settings", + "operationId": "getEmailSettings", + "tags": [ + "Email" + ], + "responses": { + "200": { + "$ref": "#/components/responses/email200" + } + } + }, + "patch": { + "summary": "Update email settings", + "operationId": "updateEmailSettings", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailSettings" + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/email200" + } + } + } + }, + "/api/emails/test": { + "post": { + "summary": "Send test email", + "operationId": "sendTestEmail", + "tags": [ + "Email" + ], + "responses": { + "200": { + "description": "Successful response" + } + } + } + }, + "/api/emails/ereader-devices": { + "post": { + "summary": "Update e-reader devices", + "operationId": "updateEReaderDevices", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ereaderDevices": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EreaderDeviceObject" + } + } + } + } + } + } + }, + "responses": { + "200": { + "$ref": "#/components/responses/ereader200" + }, + "400": { + "description": "Invalid payload" + } + } + } + }, + "/api/emails/send-ebook-to-device": { + "post": { + "summary": "Send ebook to device", + "operationId": "sendEBookToDevice", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "libraryItemId": { + "$ref": "#/components/schemas/libraryItemId" + }, + "deviceName": { + "$ref": "#/components/schemas/ereaderName" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful response" + }, + "400": { + "description": "Invalid request" + }, + "403": { + "description": "Forbidden" + }, + "404": { + "description": "Not found" + } + } + } + }, "/api/libraries": { "get": { "operationId": "getLibraries", @@ -1114,12 +1244,6 @@ "application/json": { "schema": { "type": "object", - "required": [ - "eventName", - "urls", - "titleTemplate", - "bodyTemplate" - ], "properties": { "libraryId": { "$ref": "#/components/schemas/libraryIdNullable" @@ -1142,7 +1266,13 @@ "type": { "$ref": "#/components/schemas/notificationType" } - } + }, + "required": [ + "eventName", + "urls", + "titleTemplate", + "bodyTemplate" + ] } } } @@ -1942,6 +2072,110 @@ "example": "us", "default": "us" }, + "ereaderName": { + "type": "string", + "description": "The name of the e-reader device." + }, + "EreaderDeviceObject": { + "type": "object", + "description": "An e-reader device configured to receive EPUB through e-mail.", + "properties": { + "name": { + "$ref": "#/components/schemas/ereaderName" + }, + "email": { + "type": "string", + "description": "The email address associated with the e-reader device." + }, + "availabilityOption": { + "type": "string", + "description": "The availability option for the device.", + "enum": [ + "adminOrUp", + "userOrUp", + "guestOrUp", + "specificUsers" + ] + }, + "users": { + "type": "array", + "description": "List of specific users allowed to access the device.", + "items": { + "type": "string" + } + } + }, + "required": [ + "name", + "email", + "availabilityOption" + ] + }, + "EmailSettings": { + "type": "object", + "description": "The email settings configuration for the server. This includes the credentials to send e-books and an array of e-reader devices.", + "properties": { + "id": { + "type": "string", + "description": "The unique identifier for the email settings. Currently this is always `email-settings`", + "example": "email-settings" + }, + "host": { + "type": "string", + "description": "The SMTP host address.", + "nullable": true + }, + "port": { + "type": "integer", + "format": "int32", + "description": "The port number for the SMTP server.", + "example": 465 + }, + "secure": { + "type": "boolean", + "description": "Indicates if the connection should use SSL/TLS.", + "example": true + }, + "rejectUnauthorized": { + "type": "boolean", + "description": "Indicates if unauthorized SSL/TLS certificates should be rejected.", + "example": true + }, + "user": { + "type": "string", + "description": "The username for SMTP authentication.", + "nullable": true + }, + "pass": { + "type": "string", + "description": "The password for SMTP authentication.", + "nullable": true + }, + "testAddress": { + "type": "string", + "description": "The test email address used for sending test emails.", + "nullable": true + }, + "fromAddress": { + "type": "string", + "description": "The default \"from\" email address for outgoing emails.", + "nullable": true + }, + "ereaderDevices": { + "type": "array", + "description": "List of configured e-reader devices.", + "items": { + "$ref": "#/components/schemas/EreaderDeviceObject" + } + } + }, + "required": [ + "id", + "port", + "secure", + "ereaderDevices" + ] + }, "libraryName": { "description": "The name of the library.", "type": "string", @@ -2530,6 +2764,34 @@ } } }, + "email200": { + "description": "Successful response - Email", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailSettings" + } + } + } + }, + "ereader200": { + "description": "Successful response - Ereader", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ereaderDevices": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EreaderDeviceObject" + } + } + } + } + } + } + }, "library200": { "description": "Library found.", "content": { From fa1518cb1d257187dd2fa322023ba8e4a296c93a Mon Sep 17 00:00:00 2001 From: Nicholas Wallace Date: Thu, 4 Jul 2024 03:51:54 +0000 Subject: [PATCH 6/6] Fix: wrong settings path --- docs/controllers/EmailController.yaml | 2 +- docs/openapi.json | 2 +- docs/root.yaml | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/controllers/EmailController.yaml b/docs/controllers/EmailController.yaml index 3a7d990e..8fb03043 100644 --- a/docs/controllers/EmailController.yaml +++ b/docs/controllers/EmailController.yaml @@ -23,7 +23,7 @@ components: items: $ref: '../objects/settings/EmailSettings.yaml#/components/schemas/EreaderDeviceObject' paths: - /api/emails: + /api/emails/settings: get: description: Get email settings operationId: getEmailSettings diff --git a/docs/openapi.json b/docs/openapi.json index 826bf84b..2f79a422 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -420,7 +420,7 @@ } } }, - "/api/emails": { + "/api/emails/settings": { "get": { "description": "Get email settings", "operationId": "getEmailSettings", diff --git a/docs/root.yaml b/docs/root.yaml index e3caedaa..4ac22abc 100644 --- a/docs/root.yaml +++ b/docs/root.yaml @@ -21,8 +21,8 @@ paths: $ref: './controllers/AuthorController.yaml#/paths/~1api~1authors~1{id}~1image' /api/authors/{id}/match: $ref: './controllers/AuthorController.yaml#/paths/~1api~1authors~1{id}~1match' - /api/emails: - $ref: './controllers/EmailController.yaml#/paths/~1api~1emails' + /api/emails/settings: + $ref: './controllers/EmailController.yaml#/paths/~1api~1emails~1settings' /api/emails/test: $ref: './controllers/EmailController.yaml#/paths/~1api~1emails~1test' /api/emails/ereader-devices: