From 40d0491a8207fad658879c7840ac66a6a9595249 Mon Sep 17 00:00:00 2001 From: MiguelTapTagshelf Date: Wed, 5 Jun 2024 19:13:06 -0400 Subject: [PATCH 1/5] Updated README info --- README.md | 329 +++++++++++++++++++++++++----------------------------- 1 file changed, 150 insertions(+), 179 deletions(-) diff --git a/README.md b/README.md index 1db5af2..ebfcae2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. -It provides a robust, strongly-typed interface for efficient development, with specialized domains for handling Tags, Jobs, Files, Deferred Sessions, and Data Points. +It provides a robust, strongly-typed interface for efficient development, with specialized domains for handling Files, Deferred Sessions, Tags, Jobs and Data Points. ## Alfred @@ -20,11 +20,14 @@ Alfred is a powerful document processing platform that enables you to extract, i - **Scalability**: Alfred is designed to expand its capacity seamlessly according to client needs, efficiently processing anywhere from thousands to millions of documents each day. -## Features +### Features - **Comprehensive Authentication Support**: Seamlessly handles OAuth, HMAC, and API key authentication methods, simplifying the process of connecting to the Alfred API. + - **Domain-Specific Operations**: Offers specialized support for File and Job operations, enabling developers to intuitively manage and interact with API resources. + - **Cross-Platform Compatibility**: Designed to be fully compatible across .NET Core, .NET Standard, and .NET Framework 4.7.2, ensuring broad usability in diverse development environments. + - **Minimal Dependencies**: Crafted to minimize external dependencies, facilitating an easier integration and deployment process with reduced conflict risk. ## Prerequisites @@ -32,7 +35,7 @@ Alfred is a powerful document processing platform that enables you to extract, i - .NET Core 2.1+ or .NET Framework 4.7.2+ installed on your development machine. - An active Alfred API key, HMAC credentials, or OAuth credentials for authenticating API requests. -## Installation +# Installation To integrate the Alfred API wrapper into your .NET project, install the package via NuGet: @@ -48,59 +51,51 @@ For .NET Core CLI, use the following command: Install-Package TagShelf.Alfred.ApiWrapper ``` -## Usage +# Usage -### Initialize the Client +## Initialize the Client - Begin by creating an instance of the Alfred client using your preferred authentication method along with the desired environment type (Production or Staging). The following examples demonstrate how to initialize the client with different authentication methods: +Begin by creating an instance of the Alfred client using your preferred authentication method along with the desired environment type (Production or Staging). The following examples demonstrate how to initialize the client with different authentication methods: -#### Environments description +### Environments description - **Production**: The production environment are used for live applications and real-world scenarios. It is recommended to use this environment for production-ready applications. The frontend URL for the production environment is [https://app.tagshelf.com](https://app.tagshelf.com)

- **Staging**: The staging environment is used for testing and development purposes. It is recommended to use this environment for testing and development scenarios. The frontend URL for the staging environment is [https://staging.tagshelf.com](https://staging.tagshelf.com)

-#### Authentication Methods +### Authentication Methods To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team. The following examples demonstrate how to initialize the Alfred client with different authentication methods: - For OAuth authentication, specify the method and credentials explicitly and provide the environment type (Production or Staging): - - ```csharp - var alfred = await AlfredFactory.CreateWithOAuthAsync("username", "password", EnvironmentType.Production); - ``` +For OAuth authentication, specify the method and credentials explicitly and provide the environment type (Production or Staging): - For HMAC authentication, provide the secret key, public key, and environment type (Production or Staging): - - ```csharp - var alfred = await AlfredFactory.CreateWithHmacAsync("secret_key", "public_key", EnvironmentType.Staging); - ``` +```csharp +var alfred = await AlfredFactory.CreateWithOAuthAsync("username", "password", EnvironmentType.Production); +``` - For API key authentication, use the following method with the API key and environment type (Production or Staging): +For HMAC authentication, provide the secret key, public key, and environment type (Production or Staging): - ```csharp - var alfred = await AlfredFactory.CreateWithApiKeyAsync("api_key", EnvironmentType.Staging); - ``` +```csharp +var alfred = await AlfredFactory.CreateWithHmacAsync("secret_key", "public_key", EnvironmentType.Staging); +``` -### File +For API key authentication, use the following method with the API key and environment type (Production or Staging): -With the client initialized, you're ready to perform API operations. +```csharp +var alfred = await AlfredFactory.CreateWithApiKeyAsync("api_key", EnvironmentType.Staging); +``` -These steps demonstrate how to upload a file to Alfred using the `File` domain: +## File Operations -1. Initialize the Alfred client. -2. Choose the method to upload the file (from URL or stream). -3. Create a request object with the necessary parameters. -4. Call the appropriate method to upload the file. -5. Handle the response accordingly.(The response will contain the file ID or the job ID, depending on the method used.) +With the Alfred client initialized, you can perform various API operations, including file uploads. -#### Upload File (From URL or URLs) +### Upload File (From URL or URLs) -This method enables you to upload a file from one or multiple URLs to Alfred. During the upload process, you can also specify metadata for the file. Please note that using this method will automatically trigger job processing. +This method allows you to upload a file from one or multiple URLs to Alfred. During the upload, you can specify metadata for the file. Note that this method triggers job processing automatically. - | Parameter | Type | Description | +| Parameter | Type | Description | | --- | --- | --- | | Url | string | URL of the file to upload (use url, when you have an URl to single remote file.)| |Urls | string[] | URLs of the files to upload. (Use urls, when you have URl's for multiple remote files. The current limit for this parameter is **100 elements**.) | @@ -113,177 +108,153 @@ This method enables you to upload a file from one or multiple URLs to Alfred. Du | PropagateMetadata | boolean | This parameter enables the specification of a single metadata object to be applied across multiple files from remote URLs or remote sources. When used, `propagate_metadata` ensures that the defined metadata is consistently attached to all the specified files during their upload and processing. This feature is particularly useful for maintaining uniform metadata across a batch of files, streamlining data organization and retrieval. | | ParentFilePrefix | string | The `parent_file_prefix` parameter is used to specify a virtual folder destination for the uploaded files, diverging from the default 'Inbox' folder. By setting this parameter, users can organize files into specific virtual directories, enhancing file management and accessibility within Alfred's system. | -##### Step by Step Guide +#### Example: Upload File from URL -1. The first step after initializing the Alfred client is to create a request object with the necessary parameters. The following parameters are available for the `FileUploadRequest` object:

+```csharp +// Create a request object with the necessary parameters +UploadRequest uploadRequest = new UploadRequest +{ + Urls = new List { "https://example.com/file1.pdf", "https://example.com/file2.pdf" }, + FileNames = new List { "file1.pdf", "file2.pdf" } +}; - ```csharp - // Create a request object with the necessary parameters - UploadRequest uploadRequest = new UploadRequest - { - Urls = new List { "https://pdfobject.com/pdf/sample.pdf", "https://pdfobject.com/pdf/sample.pdf" }, - FileNames = new List { "sample.pdf", "sample.pdf" }, +// Upload remote file +var uploadResult = await alfred.File.UploadAsync(uploadRequest); - }; - ``` +// Handle the response +Console.WriteLine(uploadResult.JobId); -2. Next, call the appropriate method to upload the file. In this case, we'll use the `UploadAsync` method to upload the file from the URL in this step we are uploading and triggering the magic:

+// Get job status +var jobStatus = await alfred.Job.GetAsync(uploadResult.JobId); - ```csharp - // Upload remote file - var uploadResult = await alfred.File.UploadAsync(uploadRequest); - ``` +// Check job completion +while (jobStatus.Stage != "completed") +{ + System.Threading.Thread.Sleep(1000); + jobStatus = await alfred.Job.GetAsync(uploadResult.JobId); +} -3. Handle the response accordingly. The response will contain the job ID since the `UploadAsync` method triggers job processing:

+// Retrieve data points for each file +var files = jobStatus.Files; +foreach (var file in files) +{ + var dataResult = await alfred.DataPoint.GetValuesAsync(file.FileId); + Console.WriteLine(dataResult); +} - ```csharp - Console.WriteLine(uploadResult.JobId); - ``` +``` -4. Get the job status using the `Job` domain. The following parameters are available for the `GetAsync` method:

+### Upload File from Stream - | Parameter | Type | Description | - | --- | --- | --- | - | JobId | Guid | Job ID | +This method uploads a file from a stream to Alfred and associates it with a specific session ID. Unlike other methods, it does not trigger job processing, making it ideal for uploading files that are part of a larger job. - **Example:** +| Parameter | Type | Description | +| --- | --- | --- | +| FileStream | Stream | Stream of the file to upload. | +| Filename | string | Unique name of the file within an object storage source. | +| SessionId | Guid | Session ID to associate with the file. | +| Metadata | string | JSON object or JSON array of objects containing metadata fields for a given remote file. | - ```csharp - // Get job status - var jobStatus = await alfred.Job.GetAsync(uploadResult.JobId); - ``` +#### Example: Upload File from Stream -5. Retrieve the data points using the `DataPoint` domain. Here we're going to wait for the job to complete and then get the data points for each file:

+```csharp +// Create a session ID +Guid sessionId = (await alfred.DeferredSession.CreateAsync()).SessionId; - **Example:** +// Create a request object with the necessary parameters +UploadFileRequest uploadFileRequest = new UploadFileRequest +{ + FileStream = new StreamReader("file_path\\sample.pdf").BaseStream, + FileName = "sample.pdf", + SessionId = sessionId, + Metadata = {} +}; - ```csharp - var jobstatus = alfred.Job.GetAsync(uploadResult.JobId).Result.Stage; +// Upload file from stream +var response = await alfred.File.UploadFileAsync(uploadFileRequest); - // check if the job is completed if not, wait for it to complete - while (jobstatus != "completed") - { - // sleep for 1 second to avoid hitting the API rate limit - System.Threading.Thread.Sleep(1000); - jobstatus = alfred.Job.GetAsync(uploadResult.JobId).Result.Stage; - } - // get the files to retrieve the data points - var files = alfred.Job.GetAsync(uploadResult.JobId).Result.Files; +``` - // get the data points for each file - foreach (var file in files) - { - var dataResult = alfred.DataPoint.GetValuesAsync(file.FileId).Result; - Console.WriteLine(dataResult); - } - ``` +## Job Operations -#### Upload File from Stream +### Trigger Job Processing -This method enables you to upload a file from a stream to Alfred and associate it with a specific session ID. Unlike other methods, this one does not trigger job processing, making it ideal for uploading files that are part of a larger job. +To process uploaded files, you must trigger job processing using the Job domain. - | Parameter | Type | Description | +| Parameter | Type | Description | | --- | --- | --- | -| FileStream | Stream | Stream of the file to upload. | -| Filename | string | Unique name of the file within an object storage source. | -| SessionId | Guid | Session ID to associate with the file. | -| Metadata | string | JSON object or JSON array of objects containing metadata fields for a given remote file. | +| SessionId | string | Session ID | +| Metadata | any | Metadata of the job | +| PropagateMetadata | boolean | If `true` ensures that the provided metadata at the Job level is attached to all the specified Files. | +| Merge | boolean | If `true`, when all provided Files are either images or PDFs, the system combines them into a single file for the purpose of processing. | +| Decompose | boolean | If `true`, when the provided File is a PDF, the system will decompose it into individual pages for processing. | +| Channel | string | Channel | +| ParentFilePrefix | string | The `parent_file_prefix` parameter is used to specify a virtual folder destination for the uploaded files, diverging from the default 'Inbox' folder. By setting this parameter, users can organize files into specific virtual directories, enhancing file management and accessibility within Alfred's system. | +| PageRotation | number | Page rotation | +| Container | string | Virtual container where the referenced remote file is located.| +| Filename | string | Unique name of the file within an object storage source.| +| Filenames | string[] | Array of unique names of the files within an object storage source.| + +#### Example: Trigger Job Processing + +```csharp +// Trigger job processing +Guid jobId = (await alfred.Job.CreateAsync(new CreateJobRequest { SessionId = sessionId })).JobId; + +// Get job status +var jobStatus = await alfred.Job.GetAsync(jobId); + +// Check job completion +while (jobStatus.Stage != "completed") +{ + System.Threading.Thread.Sleep(1000); + jobStatus = await alfred.Job.GetAsync(jobId); +} + +// Check if the job is completed if not, wait for it to complete +while (jobstatus != "completed") +{ + // Sleep for 1 second to avoid hitting the API rate limit + System.Threading.Thread.Sleep(1000); + jobstatus = alfred.Job.GetAsync(jobId).Result.Stage; +} + +``` + +## Data Point Operations + +### Retrive Data Points + +After job completion, retrieve data points for each file using the DataPoint domain. + +#### Example: Retrieve Data Points + +```csharp +// Get the files to retrieve the data points +var files = alfred.Job.GetAsync(jobId).Result.Files; + +// Get the data points for each file +foreach (var file in files) +{ + var dataResult = alfred.DataPoint.GetValuesAsync(file.FileId).Result; + Console.WriteLine(dataResult); +} + +``` + +## Notes + +For more information on job stages and data points, refer to the [Alfred Official Documentation](https://docs.tagshelf.dev/). +Ensure to handle any exceptions or errors that may occur during API calls for robust implementation. -##### Step by Step Guide - -1. The first step after initializing the Alfred client is to create a `session ID` using the `DeferredSession` domain. The following parameters are available for the `CreateAsync` method. This is used to associate the file with a specific session ID that can be used for further processing of all files uploaded within the same session that a single job contains:

- - ```csharp - // Create a session ID - Guid sessionId = (await alfred.DeferredSession.CreateAsync()).SessionId; - ``` - -2. Next, create a request object with the necessary parameters. The following parameters are available for the `UploadFileRequest` object:

- - ```csharp - // Create a request object with the necessary parameters - UploadFileRequest uploadFileRequest = new UploadFileRequest - { - FileStream = new StreamReader("file_path\\sample.pdf").BaseStream, - FileName = "sample.pdf", - SessionId = sessionId, - Metadata = { } - }; - ``` - -3. Next, call the appropriate method to upload the file. In this case, we'll use the `UploadFileAsync` method to upload the file from the stream unlike the previous method this one does not trigger job processing:

- - ```csharp - // Upload file from stream - var response = await alfred.File.UploadFileAsync(uploadFileRequest); - ``` - -4. Trigger the job processing using the `Job` domain. The following parameters are available for the `CreateAsync` method witch it can contain the following parameters:

- - | Parameter | Type | Description | - | --- | --- | --- | - | SessionId | string | Session ID | - | Metadata | any | Metadata of the job | - | PropagateMetadata | boolean | If `true` ensures that the provided metadata at the Job level is attached to all the specified Files. | - | Merge | boolean | If `true`, when all provided Files are either images or PDFs, the system combines them into a single file for the purpose of processing. | - | decompose | boolean | If `true`, when the provided File is a PDF, the system will decompose it into individual pages for processing. | - | Channel | string | Channel | - | ParentFilePrefix | string | The `parent_file_prefix` parameter is used to specify a virtual folder destination for the uploaded files, diverging from the default 'Inbox' folder. By setting this parameter, users can organize files into specific virtual directories, enhancing file management and accessibility within Alfred's system. | - | PageRotation | number | Page rotation | - | Container | string | Virtual container where the referenced remote file is located.| - | Filename | string | Unique name of the file within an object storage source.| - | Filenames | string[] | Array of unique names of the files within an object storage source.| - - **Example:** - - ```csharp - // Trigger job processing - Guid jobId = alfred.Job.CreateAsync(new CreateJobRequest { SessionId = sessionId}).Result.JobId; - ``` - -5. Get the job status using the `Job` domain. This way you can check the stage of the job processing. For more information about the `job stages` please visit the [Alfred documentation](https://docs.tagshelf.dev/enpoints/job/job-stages).

- **Example:** - - ```csharp - // Get job status - var jobStatus = await alfred.Job.GetAsync(jobId); - Console.WriteLine(jobStatus); - ``` - -6. Retrieve the data points using the `DataPoint` domain. Here we're going to wait for the job to complete and then get the data points for each file:

- - **Example:** - - ```csharp - var jobstatus = alfred.Job.GetAsync(jobId).Result.Stage; - - // check if the job is completed if not, wait for it to complete - while (jobstatus != "completed") - { - // sleep for 1 second to avoid hitting the API rate limit - System.Threading.Thread.Sleep(1000); - jobstatus = alfred.Job.GetAsync(jobId).Result.Stage; - } - // get the files to retrieve the data points - var files = alfred.Job.GetAsync(jobId).Result.Files; - - // get the data points for each file - foreach (var file in files) - { - var dataResult = alfred.DataPoint.GetValuesAsync(file.FileId).Result; - Console.WriteLine(dataResult); - } - - ``` - -## Contributing +# Contributing Contributions to improve `TagShelf.Alfred.ApiWrapper` are welcome. Please feel free to fork the repository, make your changes, and submit a pull request for review. -## License +# License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -## Acknowledgments +# Acknowledgments -- Thanks to all the contributors who invest their time into making `TagShelf.Alfred.ApiWrapper` better. +Thanks to all the contributors who invest their time into making `TagShelf.Alfred.ApiWrapper` better. From c7f3fdc5536681904169c6a71abb2520d2b3c876 Mon Sep 17 00:00:00 2001 From: MiguelTapTagshelf Date: Tue, 25 Jun 2024 12:57:05 -0400 Subject: [PATCH 2/5] fix: Structure of README file --- README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 136 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index ebfcae2..39927f9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. -It provides a robust, strongly-typed interface for efficient development, with specialized domains for handling Files, Deferred Sessions, Tags, Jobs and Data Points. +It provides a robust, strongly-typed interface for efficient development, with specialized domains for handling Deferred Sessions, Files, Jobs and Data Points. ## Alfred @@ -20,8 +20,6 @@ Alfred is a powerful document processing platform that enables you to extract, i - **Scalability**: Alfred is designed to expand its capacity seamlessly according to client needs, efficiently processing anywhere from thousands to millions of documents each day. -### Features - - **Comprehensive Authentication Support**: Seamlessly handles OAuth, HMAC, and API key authentication methods, simplifying the process of connecting to the Alfred API. - **Domain-Specific Operations**: Offers specialized support for File and Job operations, enabling developers to intuitively manage and interact with API resources. @@ -37,7 +35,7 @@ Alfred is a powerful document processing platform that enables you to extract, i # Installation -To integrate the Alfred API wrapper into your .NET project, install the package via NuGet: +To integrate the Alfred API wrapper into your .NET project, install the package via NuGet in the `src` folder of your project: ```bash dotnet add package TagShelf.Alfred.ApiWrapper @@ -51,41 +49,158 @@ For .NET Core CLI, use the following command: Install-Package TagShelf.Alfred.ApiWrapper ``` -# Usage +# Environment + +You will always use the production environment for all your integrations using this library. The production environment is used for live applications and real-world scenarios. It is recommended to use this environment for production-ready applications. The frontend URL for the production environment is [https://app.tagshelf.com](https://app.tagshelf.com)

-## Initialize the Client +# Authentication -Begin by creating an instance of the Alfred client using your preferred authentication method along with the desired environment type (Production or Staging). The following examples demonstrate how to initialize the client with different authentication methods: +Alfred supports three authentication methods: OAuth, HMAC, and App API Key. Each method is suited for different scenarios. To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team. -### Environments description +|OAuth|| +|--|--| +| **When to Use** | Ideal for web portals needing integration with document parsers or API-driven services, especially when users access through browsers. Suitable for short-lived browser sessions and scenarios requiring scoped, secure access.| +| **Benefits** | Enhanced security via token use, flexible access control, and a user-friendly experience with periodic re-authentication.| +| **Best Practices**| Secure token storage and graceful handling of token expiration.| -- **Production**: The production environment are used for live applications and real-world scenarios. It is recommended to use this environment for production-ready applications. The frontend URL for the production environment is [https://app.tagshelf.com](https://app.tagshelf.com)

+To initialize the client for OAuth authentication, specify the credentials explicitly: + +```csharp +var alfred = await AlfredFactory.CreateWithOAuthAsync("username", "password", EnvironmentType.Production); +``` -- **Staging**: The staging environment is used for testing and development purposes. It is recommended to use this environment for testing and development scenarios. The frontend URL for the staging environment is [https://staging.tagshelf.com](https://staging.tagshelf.com)

+|HMAC|| +|--|--| +| **When to Use** | Best for applications needing individual account access without token management, ensuring secure transactions.| +| **Benefits** | Secure request authentication with a unique signature per request.| +| **Best Practices** | Secure key management, include timestamps to prevent replay attacks, and use a dynamic nonce for each request.| -### Authentication Methods +To initialize the client for HMAC authentication, provide the secret key and public key: -To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team. +```csharp +var alfred = await AlfredFactory.CreateWithHmacAsync("secret_key", "public_key", EnvironmentType.Production); +``` -The following examples demonstrate how to initialize the Alfred client with different authentication methods: +|App API Key|| +|--|--| +| **When to Use** | Recommended for server-to-server communication, automated processes, and background services where user interaction is not feasible.| +| **Benefits** | Non-interactive yet robust authentication, simplicity, and easy access control.| +| **Best Practices** | Secure storage of API keys, apply the principle of least privilege, and regularly rotate keys to minimize compromise risks.| -For OAuth authentication, specify the method and credentials explicitly and provide the environment type (Production or Staging): +To initialize the client for API key authentication, provide the API key: ```csharp -var alfred = await AlfredFactory.CreateWithOAuthAsync("username", "password", EnvironmentType.Production); +var alfred = await AlfredFactory.CreateWithApiKeyAsync("api_key", EnvironmentType.Staging); +``` + +# Getting Started + +This library covers 6 different domains: +- [Tagshelf](#tagshelf-tagshelf-domain) +- [Deferred Sessions](#deferred-sessions-deferred-sessions-domain) +- [Files](#files-files-domain) +- [Jobs](#jobs-jobs-domain) +- [Data Points](#data-points-data-points-domain) +- [Account](#account-account-domain) + +## Tagshelf {#tagshelf-domain} + +The Tagshelf API namespace serves as a dedicated domain within the API for platform status and identity queries. This namespace is tailored to provide essential functionalities related to the operational status and user context of the platform. It encompasses endpoints that are crucial for system health checks, user identity verification, and basic connectivity tests. + +### Check Platform Operational Status + +This endpoint offers a quick way to check the overall operational status of the platform. + +```csharp +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("admin@tagshelf.com", "T@gSh3lf", EnvironmentType.Staging); + +// Get the Platform Operational Status +TagshelfStatusResult status = await alfred.Tagshelf.StatusAsync(); + +// Print the Result +Console.WriteLine(status); ``` +**Result** +```cmd +ApiVersion: 1.47.6.0, DbStatus: online +``` + +### Retrieve User Identity Information -For HMAC authentication, provide the secret key, public key, and environment type (Production or Staging): +This endpoint provides information about the currently authenticated user. ```csharp -var alfred = await AlfredFactory.CreateWithHmacAsync("secret_key", "public_key", EnvironmentType.Staging); +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("admin@tagshelf.com", "T@gSh3lf", EnvironmentType.Staging); + +// Get the Platform Operational Status +WhoAmIResult whoami = await alfred.Tagshelf.WhoAmIAsync(); + +// Print the Result +Console.WriteLine(whoami); ``` +**Result** +```cmd +UserName: admin@tagshelf.com, Name: Admin Tagshelf, Roles: Admin, Developer, Status: active, Company: TAGSHELF, App: , AppId: 00000000-0000-0000-0000-000000000000, RequestOriginIpAddress: 152.0.135.113:20845 +``` + +### Conduct a Basic Connectivity Test -For API key authentication, use the following method with the API key and environment type (Production or Staging): +The `ping` endpoint is used to perform a basic connectivity test to the platform. ```csharp -var alfred = await AlfredFactory.CreateWithApiKeyAsync("api_key", EnvironmentType.Staging); +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("admin@tagshelf.com", "T@gSh3lf", EnvironmentType.Staging); + +// Get the Platform Operational Status +PingResult ping = await alfred.Tagshelf.PingAsync(); + +// Print the Result +Console.WriteLine(ping); ``` +**Result** +```cmd +Pong: admin@tagshelf.com +``` + +## Deferred Sessions {#deferred-sessions-domain} + +A Deferred Session in Alfred is a mechanism designed for asynchronous file uploads, integral to the document processing workflow. It serves as a container or grouping for files that are uploaded at different times or from various sources, but are all part of a single processing task or Job. + +### Create a new Deferred Session + + + + + +### Retrieve Details of a Specific Deferred Session + + + + + + +## Files {#files-domain} + +In Alfred, a file is an individual document or data unit undergoing specialized operations tailored for document analysis and management. It is processed by the platform for tasks such as classification, optical character recognition (OCR), and data extraction. Each file, as a distinct entity, transitions through various statuses, which mark its progress in the automated workflow. + + + + + + + + + + +## Jobs {#jobs-domain} + +## Data Points {#data-points-domain} + +## Account {#account-domain} + + ## File Operations @@ -242,10 +357,9 @@ foreach (var file in files) ``` -## Notes +# Notes -For more information on job stages and data points, refer to the [Alfred Official Documentation](https://docs.tagshelf.dev/). -Ensure to handle any exceptions or errors that may occur during API calls for robust implementation. +For more information on job stages, data points and other parameters to customize your calls to Alfreds' different endpoints, refer to the [Alfred Official Documentation](https://docs.tagshelf.dev/). Ensure to handle any exceptions or errors that may occur during API calls for robust implementation. # Contributing From ac1720608b8c7fbafa5d5b0cfc3ed4b0d26f9294 Mon Sep 17 00:00:00 2001 From: MiguelTapTagshelf Date: Fri, 28 Jun 2024 19:48:41 -0400 Subject: [PATCH 3/5] fix: Content of README file --- README.md | 422 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 288 insertions(+), 134 deletions(-) diff --git a/README.md b/README.md index 39927f9..9a65071 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # Overview -The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. - -It provides a robust, strongly-typed interface for efficient development, with specialized domains for handling Deferred Sessions, Files, Jobs and Data Points. +The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. It includes specialized domains for handling Deferred Sessions, Files, Jobs and Data Points. ## Alfred @@ -55,7 +53,7 @@ You will always use the production environment for all your integrations using t # Authentication -Alfred supports three authentication methods: OAuth, HMAC, and App API Key. Each method is suited for different scenarios. To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team. +Alfred supports three authentication methods: OAuth, HMAC, and App API Key. Each method is suited for different scenarios. To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team at support@tagshelf.com. |OAuth|| |--|--| @@ -63,7 +61,7 @@ Alfred supports three authentication methods: OAuth, HMAC, and App API Key. Each | **Benefits** | Enhanced security via token use, flexible access control, and a user-friendly experience with periodic re-authentication.| | **Best Practices**| Secure token storage and graceful handling of token expiration.| -To initialize the client for OAuth authentication, specify the credentials explicitly: +To initialize the client for OAuth authentication, specify your Tagshelf credentials explicitly: ```csharp var alfred = await AlfredFactory.CreateWithOAuthAsync("username", "password", EnvironmentType.Production); @@ -90,20 +88,20 @@ var alfred = await AlfredFactory.CreateWithHmacAsync("secret_key", "public_key", To initialize the client for API key authentication, provide the API key: ```csharp -var alfred = await AlfredFactory.CreateWithApiKeyAsync("api_key", EnvironmentType.Staging); +var alfred = await AlfredFactory.CreateWithApiKeyAsync("api_key", EnvironmentType.Production); ``` # Getting Started This library covers 6 different domains: -- [Tagshelf](#tagshelf-tagshelf-domain) -- [Deferred Sessions](#deferred-sessions-deferred-sessions-domain) -- [Files](#files-files-domain) -- [Jobs](#jobs-jobs-domain) -- [Data Points](#data-points-data-points-domain) -- [Account](#account-account-domain) +- [Tagshelf](#tagshelf) +- [Deferred Sessions](#deferred-sessions) +- [Files](#files) +- [Jobs](#jobs) +- [Data Points](#data-points) +- [Account](#account) -## Tagshelf {#tagshelf-domain} +## Tagshelf The Tagshelf API namespace serves as a dedicated domain within the API for platform status and identity queries. This namespace is tailored to provide essential functionalities related to the operational status and user context of the platform. It encompasses endpoints that are crucial for system health checks, user identity verification, and basic connectivity tests. @@ -112,13 +110,18 @@ The Tagshelf API namespace serves as a dedicated domain within the API for platf This endpoint offers a quick way to check the overall operational status of the platform. ```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.Tagshelf.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; + // Authentication -var alfred = await AlfredFactory.CreateWithOAuthAsync("admin@tagshelf.com", "T@gSh3lf", EnvironmentType.Staging); +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); // Get the Platform Operational Status TagshelfStatusResult status = await alfred.Tagshelf.StatusAsync(); -// Print the Result +// Print the Results Console.WriteLine(status); ``` **Result** @@ -131,18 +134,23 @@ ApiVersion: 1.47.6.0, DbStatus: online This endpoint provides information about the currently authenticated user. ```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.Tagshelf.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; + // Authentication -var alfred = await AlfredFactory.CreateWithOAuthAsync("admin@tagshelf.com", "T@gSh3lf", EnvironmentType.Staging); +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); // Get the Platform Operational Status WhoAmIResult whoami = await alfred.Tagshelf.WhoAmIAsync(); -// Print the Result +// Print the Results Console.WriteLine(whoami); ``` **Result** ```cmd -UserName: admin@tagshelf.com, Name: Admin Tagshelf, Roles: Admin, Developer, Status: active, Company: TAGSHELF, App: , AppId: 00000000-0000-0000-0000-000000000000, RequestOriginIpAddress: 152.0.135.113:20845 +UserName: example@mail.com, Name: John Doe, Roles: Admin, Developer, Status: active, Company: TAGSHELF, App: , AppId: 00000000-0000-0000-0000-000000000000, RequestOriginIpAddress: 152.0.135.113:20845 ``` ### Conduct a Basic Connectivity Test @@ -150,211 +158,357 @@ UserName: admin@tagshelf.com, Name: Admin Tagshelf, Roles: Admin, Developer, Sta The `ping` endpoint is used to perform a basic connectivity test to the platform. ```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.Tagshelf.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; + // Authentication -var alfred = await AlfredFactory.CreateWithOAuthAsync("admin@tagshelf.com", "T@gSh3lf", EnvironmentType.Staging); +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); // Get the Platform Operational Status PingResult ping = await alfred.Tagshelf.PingAsync(); -// Print the Result +// Print the Results Console.WriteLine(ping); ``` **Result** ```cmd -Pong: admin@tagshelf.com +Pong: example@mail.com ``` -## Deferred Sessions {#deferred-sessions-domain} +## Deferred Sessions A Deferred Session in Alfred is a mechanism designed for asynchronous file uploads, integral to the document processing workflow. It serves as a container or grouping for files that are uploaded at different times or from various sources, but are all part of a single processing task or Job. ### Create a new Deferred Session +This endpoint initiates a new Deferred Session in Alfred for asynchronous, staggered file uploads for a future Job. +```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.DeferredSession.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); +// Create a Session +CreateSessionResult sessionId = await alfred.DeferredSession.CreateAsync(); -### Retrieve Details of a Specific Deferred Session - - - +// Print the Results +Console.WriteLine(sessionId); +``` +**Result** +```cmd +SessionId: 4910a915-1c79-4d10-8c2f-ffa0072bc203 +``` +### Retrieve Details of a Specific Deferred Session +This endpoint provides detailed information about a Deferred Session, identified by its unique `id`. -## Files {#files-domain} +```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.DeferredSession.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; -In Alfred, a file is an individual document or data unit undergoing specialized operations tailored for document analysis and management. It is processed by the platform for tasks such as classification, optical character recognition (OCR), and data extraction. Each file, as a distinct entity, transitions through various statuses, which mark its progress in the automated workflow. +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); +// Create a Session +CreateSessionResult sessionId = await alfred.DeferredSession.CreateAsync(); +// Get Session Details +SessionDetailResult sessiondetails = await alfred.DeferredSession.GetAsync(sessionId.SessionId); +// Print the Results +Console.WriteLine(sessiondetails); +``` +**Result** +```cmd +Id: 7b3ca596-339a-4fe1-a05b-921f64fa4a42, CreationDate: 6/26/2024 7:36:36 PM, UpdateDate: 6/26/2024 7:36:36 PM, Status: open, UserName: example@mail.com, CompanyId: 286e2ed0-3626-4faa-a745-8ebf3488fbd7, JobId: +``` +## Files +In Alfred, a file is an individual document or data unit undergoing specialized operations tailored for document analysis and management. It is processed by the platform for tasks such as classification, optical character recognition (OCR), and data extraction. Each file, as a distinct entity, transitions through various statuses, which mark its progress in the automated workflow. +You can find the full list of job statuses and their description in the [Alfred Official Documentation](https://docs.tagshelf.dev/enpoints/file/file-status). +### Upload Files from Remote Sources +This endpoint facilitates the uploading of files from remote sources, accommodating various types of external storage like URLs, or Blob storage from cloud providers including AWS, GCP, or DigitalOcean. +In Alfred, uploading a file via this endpoint contributes to the initiation of a Job, which encompasses a series of processes over several files. -## Jobs {#jobs-domain} +You can find the full list of parameters you can use in the [Alfred Official Documentation](https://docs.tagshelf.dev/enpoints/file#upload-files-from-remote-sources). -## Data Points {#data-points-domain} +```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using AlfredApiWrapper.Domains.File.Requests; +using TagShelf.Alfred.ApiWrapper.Domains.File.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; -## Account {#account-domain} +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); +// Create a Request Object with the Necessary Parameters +UploadRequest uploadRequest = new UploadRequest +{ + Urls = new List { "https://example.com/file1.pdf", "https://example.com/file2.pdf" }, + FileNames = new List { "file1.pdf", "file2.pdf" } +}; +// Upload Remote File +FileUploadResult uploadResult = await alfred.File.UploadAsync(uploadRequest); -## File Operations +// Print the Results +Console.WriteLine(uploadResult); +``` +**Result** +```cmd +Job ID: ffad4bcb-0d38-47a6-9886-22e98818ee84 +``` -With the Alfred client initialized, you can perform various API operations, including file uploads. +### Upload File by Stream -### Upload File (From URL or URLs) +Uploads a single remote file to the system's pipeline. Before using this endpoint, you must have the `id` of a deferred session already created. -This method allows you to upload a file from one or multiple URLs to Alfred. During the upload, you can specify metadata for the file. Note that this method triggers job processing automatically. +This endpoint uploads a file from a stream to Alfred and associates it with a specific session `id`. It does not trigger job processing, making it ideal for uploading files that are part of a larger job. | Parameter | Type | Description | | --- | --- | --- | -| Url | string | URL of the file to upload (use url, when you have an URl to single remote file.)| -|Urls | string[] | URLs of the files to upload. (Use urls, when you have URl's for multiple remote files. The current limit for this parameter is **100 elements**.) | -| Source | string | Configured object storage source name. Ideal for referring to files hosted in existing cloud containers. When used, **file_name** and **container** are required. | -|Container | string | Virtual container where the referenced remote file is located. When used, **source** and **file_name** are required.| -| Filename | string | Unique name of the file within an object storage source. When used, **source** and **container** are required.| -| Filenames | string[] | Array of unique names of the files within an object storage source. When used, **source** and **container** are required.| -| Merge | boolean | Boolean value [true/false] - When set to true, will merge all of the remote files into a single PDF file. All of the remote files MUST be images.

By default this field is set to **false**. | -| Metadata | string | JSON object or JSON array of objects containing metadata fields for a given remote file.

When merge field is set to **false**:

When using the urls field this should be a JSON object array that matches the urls field array length.

When using the url field the metadata field should be a JSON object.

When the merge field is set to true: The metadata field should be a JSON object.| -| PropagateMetadata | boolean | This parameter enables the specification of a single metadata object to be applied across multiple files from remote URLs or remote sources. When used, `propagate_metadata` ensures that the defined metadata is consistently attached to all the specified files during their upload and processing. This feature is particularly useful for maintaining uniform metadata across a batch of files, streamlining data organization and retrieval. | -| ParentFilePrefix | string | The `parent_file_prefix` parameter is used to specify a virtual folder destination for the uploaded files, diverging from the default 'Inbox' folder. By setting this parameter, users can organize files into specific virtual directories, enhancing file management and accessibility within Alfred's system. | - -#### Example: Upload File from URL +| FileStream | Stream | Stream of the file to upload. | +| Filename | string | Unique name of the file within an object storage source. | +| SessionId | Guid | Session ID to associate with the file. | +| Metadata | string | JSON object or JSON array of objects containing metadata fields for a given remote file. | ```csharp -// Create a request object with the necessary parameters -UploadRequest uploadRequest = new UploadRequest +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using AlfredApiWrapper.Domains.File.Requests; +using TagShelf.Alfred.ApiWrapper.Domains.File.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; + +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); + +// Create a Deferred Session +Guid sessionId = (await alfred.DeferredSession.CreateAsync()).SessionId; + +// Create a Request Object with the Necessary Parameters +UploadFileRequest uploadFileRequest = new UploadFileRequest { - Urls = new List { "https://example.com/file1.pdf", "https://example.com/file2.pdf" }, - FileNames = new List { "file1.pdf", "file2.pdf" } + FileStream = new StreamReader("file_path\\sample.pdf").BaseStream, + FileName = "sample.pdf", + SessionId = sessionId, + Metadata = { } }; -// Upload remote file -var uploadResult = await alfred.File.UploadAsync(uploadRequest); +// Upload File From Stream +UploadFileResult uploadFileResult = await alfred.File.UploadFileAsync(uploadFileRequest); + +// Print the Results +Console.WriteLine(uploadFileResult); +``` +**Result** +```cmd +File ID: 6783e660-2e97-4534-b559-5c90b4d30d41 +``` -// Handle the response -Console.WriteLine(uploadResult.JobId); +### Get File Details by ID -// Get job status -var jobStatus = await alfred.Job.GetAsync(uploadResult.JobId); +Get all file details by file `id`. -// Check job completion -while (jobStatus.Stage != "completed") -{ - System.Threading.Thread.Sleep(1000); - jobStatus = await alfred.Job.GetAsync(uploadResult.JobId); -} +```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.File.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; -// Retrieve data points for each file -var files = jobStatus.Files; -foreach (var file in files) -{ - var dataResult = await alfred.DataPoint.GetValuesAsync(file.FileId); - Console.WriteLine(dataResult); -} +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); + +// File ID +Guid fileid = Guid.Parse("6783e660-2e97-4534-b559-5c90b4d30d41"); +// Upload File From Stream +FileDetailResult filedetail = await alfred.File.GetAsync(fileid); + +// Print the Results +Console.WriteLine(filedetail); +``` +**Result** +```cmd +Id: 6783e660-2e97-4534-b559-5c90b4d30d41, FileName: sample.pdf, Status: uploaded, ContentType: application/octet-stream, FileSize: 540497 bytes, CreationDate: 6/27/2024 6:51:42 PM ``` -### Upload File from Stream +### Download File by ID -This method uploads a file from a stream to Alfred and associates it with a specific session ID. Unlike other methods, it does not trigger job processing, making it ideal for uploading files that are part of a larger job. +Returns a byte stream representing the data for a given file. -| Parameter | Type | Description | -| --- | --- | --- | -| FileStream | Stream | Stream of the file to upload. | -| Filename | string | Unique name of the file within an object storage source. | -| SessionId | Guid | Session ID to associate with the file. | -| Metadata | string | JSON object or JSON array of objects containing metadata fields for a given remote file. | +```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.File.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; + +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); + +// File ID +Guid fileid = Guid.Parse("6783e660-2e97-4534-b559-5c90b4d30d41"); + +// Upload File From Stream +FileDownloadResult download = await alfred.File.DownloadAsync(fileid); + +// Print the Results +Console.WriteLine(download); +``` +**Result** +Returns the File as a stream. + +## Jobs -#### Example: Upload File from Stream +A Job in Alfred represents a single unit of work that performs a sequence of operations on one or more files for the purpose of document classification, extraction, and indexing. It is an asynchronous entity, orchestrated by a state machine that manages its progress through various stages. + +You can find the full list of job stages and their description in the [Alfred Official Documentation](https://docs.tagshelf.dev/enpoints/job/job-stages). + +### Create a New Job and Close the Deferred Upload Session + +This endpoint is used for creating a new Job in Alfred. It serves a dual purpose: it finalizes the deferred upload session, ensuring that all files needed for the Job are uploaded, and initiates the Job itself. + +The only parameter that is **required** for this endpoint is `session_id`. You can find the full list of parameters you can use in the [Alfred Official Documentation](https://docs.tagshelf.dev/enpoints/job#create-a-new-job-and-close-the-deferred-upload-session). ```csharp -// Create a session ID +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.Job.Requests; +using TagShelf.Alfred.ApiWrapper.Domains.Job.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; + +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); + +// Create a Deferred Session Guid sessionId = (await alfred.DeferredSession.CreateAsync()).SessionId; -// Create a request object with the necessary parameters -UploadFileRequest uploadFileRequest = new UploadFileRequest +// Create a Request Object with the Necessary Parameters +CreateJobRequest request = new CreateJobRequest { - FileStream = new StreamReader("file_path\\sample.pdf").BaseStream, - FileName = "sample.pdf", - SessionId = sessionId, - Metadata = {} + SessionId = sessionId }; -// Upload file from stream -var response = await alfred.File.UploadFileAsync(uploadFileRequest); +// Create a New Job +CreateJobResult job = await alfred.Job.CreateAsync(request); +// Print the Results +Console.WriteLine(job); +``` +**Result** +```cmd +Job ID: ffad4bcb-0d38-47a6-9886-22e98818ee84 ``` -## Job Operations +### Retrieve Detailed Information About a Specific Job -### Trigger Job Processing +This endpoint provides comprehensive details about a Job identified by its unique `id`. -To process uploaded files, you must trigger job processing using the Job domain. +```csharp +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.Job.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; -| Parameter | Type | Description | -| --- | --- | --- | -| SessionId | string | Session ID | -| Metadata | any | Metadata of the job | -| PropagateMetadata | boolean | If `true` ensures that the provided metadata at the Job level is attached to all the specified Files. | -| Merge | boolean | If `true`, when all provided Files are either images or PDFs, the system combines them into a single file for the purpose of processing. | -| Decompose | boolean | If `true`, when the provided File is a PDF, the system will decompose it into individual pages for processing. | -| Channel | string | Channel | -| ParentFilePrefix | string | The `parent_file_prefix` parameter is used to specify a virtual folder destination for the uploaded files, diverging from the default 'Inbox' folder. By setting this parameter, users can organize files into specific virtual directories, enhancing file management and accessibility within Alfred's system. | -| PageRotation | number | Page rotation | -| Container | string | Virtual container where the referenced remote file is located.| -| Filename | string | Unique name of the file within an object storage source.| -| Filenames | string[] | Array of unique names of the files within an object storage source.| - -#### Example: Trigger Job Processing +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); + +// Job ID +Guid jobid = Guid.Parse("ffad4bcb-0d38-47a6-9886-22e98818ee84"); + +// Get Job Details +JobDetailResult jobdetail = await alfred.Job.GetAsync(jobid); + +// Print the Results +Console.WriteLine(jobdetail); +``` +**Result** +```cmd +ffad4bcb-0d38-47a6-9886-22e98818ee84 - example@mail.com - completed - 6/26/2024 8:43:57 PM +``` + +## Data Points + +> **Important:** Data Points where previously known as Metadata. + +In Alfred's Intelligent Document Processing (IDP) platform, the concept of data points is intricately linked with tags and plays a vital role in extracting specific data points from content, particularly files. Data points in Alfred are unique in that they are associated with a specific tag and encompass information intended to be extracted based on the file's classified content. + +Data point values are critical components that represent the extracted information based on the data points defined for each tag. + +### Get Data Points Values from File ID + +Get a list of metadata values from File ID ```csharp -// Trigger job processing -Guid jobId = (await alfred.Job.CreateAsync(new CreateJobRequest { SessionId = sessionId })).JobId; +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.DataPoint.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; -// Get job status -var jobStatus = await alfred.Job.GetAsync(jobId); +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); -// Check job completion -while (jobStatus.Stage != "completed") -{ - System.Threading.Thread.Sleep(1000); - jobStatus = await alfred.Job.GetAsync(jobId); -} +// File ID +Guid fileid = Guid.Parse("010065f8-c515-465b-9bd4-13a1fd36e908"); -// Check if the job is completed if not, wait for it to complete -while (jobstatus != "completed") -{ - // Sleep for 1 second to avoid hitting the API rate limit - System.Threading.Thread.Sleep(1000); - jobstatus = alfred.Job.GetAsync(jobId).Result.Stage; -} +// Get the Data Point Values +List datapointvalues = await alfred.DataPoint.GetValuesAsync(fileid); +// Print the Results +Console.WriteLine(datapointvalues); +``` +**Result** +```cmd +Id: c40e0384-9d4b-4e12-83e6-29a181f31254, FileLogId: 9ddb16be-2875-4891-9edc-ec457adc252c, MetadataId: 813966a3-f340-42c7-a1eb-188718c46a8a, MetadataName: InvoiceNo, Value: 222436, ClassificationScore: 1.0 ``` -## Data Point Operations +## Account -### Retrive Data Points +This namespace is designed to facilitate crucial account-related activities and insights. It encompasses a range of functionalities essential for enhancing user interaction and management within the platform. -After job completion, retrieve data points for each file using the DataPoint domain. +### Set a Webhook for a Given Account -#### Example: Retrieve Data Points +Sets a web hook for a given account. An HTTP end-point will get notified every time an event is triggered within the system. ```csharp -// Get the files to retrieve the data points -var files = alfred.Job.GetAsync(jobId).Result.Files; +// Imports +using TagShelf.Alfred.ApiWrapper.Core; +using TagShelf.Alfred.ApiWrapper.Domains.Account.Requests; +using TagShelf.Alfred.ApiWrapper.Domains.Account.Results; +using TagShelf.Alfred.ApiWrapper.Enumerations; -// Get the data points for each file -foreach (var file in files) +// Authentication +var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "password", EnvironmentType.Production); + +// Create a Request Object with the Necessary Parameters +WebhookSetupRequest request = new WebhookSetupRequest { - var dataResult = alfred.DataPoint.GetValuesAsync(file.FileId).Result; - Console.WriteLine(dataResult); -} + Url = "https://my.webhook.co/path" +}; + +// Set a Webhook for a Given Account +WebhookSetupResult webhook = await alfred.Account.SetupWebhookAsync(request); +// Print the Results +Console.WriteLine(webhook); +``` +**Result** +```cmd +Id: 559167cb-4c76-4e28-bf15-34cbf614119c, Url: https://my.webhook.co/path ``` # Notes From 1d4ae3c76fce02f572b520cef9c3d9435d04a9e1 Mon Sep 17 00:00:00 2001 From: MiguelTapTagshelf Date: Sat, 6 Jul 2024 17:23:56 -0400 Subject: [PATCH 4/5] fix: Removed examples and added Reference --- README.md | 99 ++++--------------------------------------------------- 1 file changed, 6 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 9a65071..680ee15 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Overview -The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. It includes specialized domains for handling Deferred Sessions, Files, Jobs and Data Points. +The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. It includes specialized domains for handling [Deferred Sessions](#deferred-sessions), [Files](#files), [Jobs](#jobs) and [Data Points](#data-points). + +This library serves as a wrapper for our HTTP API, which you can find the documentation for in this link https://docs.tagshelf.dev/ ## Alfred @@ -53,7 +55,7 @@ You will always use the production environment for all your integrations using t # Authentication -Alfred supports three authentication methods: OAuth, HMAC, and App API Key. Each method is suited for different scenarios. To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team at support@tagshelf.com. +Alfred supports three authentication methods: OAuth, HMAC, and API Key. Each method is suited for different scenarios. To obtain the necessary credentials for the following authentication methods, please refer to the [Alfred API documentation](https://docs.tagshelf.dev/authentication) or contact the Alfred support team at support@tagshelf.com. |OAuth|| |--|--| @@ -79,7 +81,7 @@ To initialize the client for HMAC authentication, provide the secret key and pub var alfred = await AlfredFactory.CreateWithHmacAsync("secret_key", "public_key", EnvironmentType.Production); ``` -|App API Key|| +|API Key|| |--|--| | **When to Use** | Recommended for server-to-server communication, automated processes, and background services where user interaction is not feasible.| | **Benefits** | Non-interactive yet robust authentication, simplicity, and easy access control.| @@ -120,13 +122,6 @@ var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "passw // Get the Platform Operational Status TagshelfStatusResult status = await alfred.Tagshelf.StatusAsync(); - -// Print the Results -Console.WriteLine(status); -``` -**Result** -```cmd -ApiVersion: 1.47.6.0, DbStatus: online ``` ### Retrieve User Identity Information @@ -144,13 +139,6 @@ var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "passw // Get the Platform Operational Status WhoAmIResult whoami = await alfred.Tagshelf.WhoAmIAsync(); - -// Print the Results -Console.WriteLine(whoami); -``` -**Result** -```cmd -UserName: example@mail.com, Name: John Doe, Roles: Admin, Developer, Status: active, Company: TAGSHELF, App: , AppId: 00000000-0000-0000-0000-000000000000, RequestOriginIpAddress: 152.0.135.113:20845 ``` ### Conduct a Basic Connectivity Test @@ -168,13 +156,6 @@ var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "passw // Get the Platform Operational Status PingResult ping = await alfred.Tagshelf.PingAsync(); - -// Print the Results -Console.WriteLine(ping); -``` -**Result** -```cmd -Pong: example@mail.com ``` ## Deferred Sessions @@ -196,13 +177,6 @@ var alfred = await AlfredFactory.CreateWithOAuthAsync("example@mail.com", "passw // Create a Session CreateSessionResult sessionId = await alfred.DeferredSession.CreateAsync(); - -// Print the Results -Console.WriteLine(sessionId); -``` -**Result** -```cmd -SessionId: 4910a915-1c79-4d10-8c2f-ffa0072bc203 ``` ### Retrieve Details of a Specific Deferred Session @@ -223,13 +197,6 @@ CreateSessionResult sessionId = await alfred.DeferredSession.CreateAsync(); // Get Session Details SessionDetailResult sessiondetails = await alfred.DeferredSession.GetAsync(sessionId.SessionId); - -// Print the Results -Console.WriteLine(sessiondetails); -``` -**Result** -```cmd -Id: 7b3ca596-339a-4fe1-a05b-921f64fa4a42, CreationDate: 6/26/2024 7:36:36 PM, UpdateDate: 6/26/2024 7:36:36 PM, Status: open, UserName: example@mail.com, CompanyId: 286e2ed0-3626-4faa-a745-8ebf3488fbd7, JobId: ``` ## Files @@ -265,13 +232,6 @@ UploadRequest uploadRequest = new UploadRequest // Upload Remote File FileUploadResult uploadResult = await alfred.File.UploadAsync(uploadRequest); - -// Print the Results -Console.WriteLine(uploadResult); -``` -**Result** -```cmd -Job ID: ffad4bcb-0d38-47a6-9886-22e98818ee84 ``` ### Upload File by Stream @@ -311,13 +271,6 @@ UploadFileRequest uploadFileRequest = new UploadFileRequest // Upload File From Stream UploadFileResult uploadFileResult = await alfred.File.UploadFileAsync(uploadFileRequest); - -// Print the Results -Console.WriteLine(uploadFileResult); -``` -**Result** -```cmd -File ID: 6783e660-2e97-4534-b559-5c90b4d30d41 ``` ### Get File Details by ID @@ -338,13 +291,6 @@ Guid fileid = Guid.Parse("6783e660-2e97-4534-b559-5c90b4d30d41"); // Upload File From Stream FileDetailResult filedetail = await alfred.File.GetAsync(fileid); - -// Print the Results -Console.WriteLine(filedetail); -``` -**Result** -```cmd -Id: 6783e660-2e97-4534-b559-5c90b4d30d41, FileName: sample.pdf, Status: uploaded, ContentType: application/octet-stream, FileSize: 540497 bytes, CreationDate: 6/27/2024 6:51:42 PM ``` ### Download File by ID @@ -365,12 +311,7 @@ Guid fileid = Guid.Parse("6783e660-2e97-4534-b559-5c90b4d30d41"); // Upload File From Stream FileDownloadResult download = await alfred.File.DownloadAsync(fileid); - -// Print the Results -Console.WriteLine(download); ``` -**Result** -Returns the File as a stream. ## Jobs @@ -405,13 +346,6 @@ CreateJobRequest request = new CreateJobRequest // Create a New Job CreateJobResult job = await alfred.Job.CreateAsync(request); - -// Print the Results -Console.WriteLine(job); -``` -**Result** -```cmd -Job ID: ffad4bcb-0d38-47a6-9886-22e98818ee84 ``` ### Retrieve Detailed Information About a Specific Job @@ -432,13 +366,6 @@ Guid jobid = Guid.Parse("ffad4bcb-0d38-47a6-9886-22e98818ee84"); // Get Job Details JobDetailResult jobdetail = await alfred.Job.GetAsync(jobid); - -// Print the Results -Console.WriteLine(jobdetail); -``` -**Result** -```cmd -ffad4bcb-0d38-47a6-9886-22e98818ee84 - example@mail.com - completed - 6/26/2024 8:43:57 PM ``` ## Data Points @@ -451,7 +378,7 @@ Data point values are critical components that represent the extracted informati ### Get Data Points Values from File ID -Get a list of metadata values from File ID +Get a list of metadata values from File ID. ```csharp // Imports @@ -467,13 +394,6 @@ Guid fileid = Guid.Parse("010065f8-c515-465b-9bd4-13a1fd36e908"); // Get the Data Point Values List datapointvalues = await alfred.DataPoint.GetValuesAsync(fileid); - -// Print the Results -Console.WriteLine(datapointvalues); -``` -**Result** -```cmd -Id: c40e0384-9d4b-4e12-83e6-29a181f31254, FileLogId: 9ddb16be-2875-4891-9edc-ec457adc252c, MetadataId: 813966a3-f340-42c7-a1eb-188718c46a8a, MetadataName: InvoiceNo, Value: 222436, ClassificationScore: 1.0 ``` ## Account @@ -502,13 +422,6 @@ WebhookSetupRequest request = new WebhookSetupRequest // Set a Webhook for a Given Account WebhookSetupResult webhook = await alfred.Account.SetupWebhookAsync(request); - -// Print the Results -Console.WriteLine(webhook); -``` -**Result** -```cmd -Id: 559167cb-4c76-4e28-bf15-34cbf614119c, Url: https://my.webhook.co/path ``` # Notes From a7158e2d3e6be2345e8b1854fd2fa26d3e4cb5df Mon Sep 17 00:00:00 2001 From: Miguel Tapia <148381224+MiguelTapTagshelf@users.noreply.github.com> Date: Sat, 6 Jul 2024 18:27:46 -0400 Subject: [PATCH 5/5] Update README.md Co-authored-by: Mateh Elismar <31004078+MatehElismar@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 680ee15..f3142d2 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The `TagShelf.Alfred.ApiWrapper` is a comprehensive .NET library designed to facilitate seamless interactions with the Alfred API. It's tailored to support a wide range of .NET applications, from modern .NET Core and .NET Standard projects to legacy .NET Framework 4.7.2 applications, providing a robust, strongly-typed interface for efficient development. It includes specialized domains for handling [Deferred Sessions](#deferred-sessions), [Files](#files), [Jobs](#jobs) and [Data Points](#data-points). -This library serves as a wrapper for our HTTP API, which you can find the documentation for in this link https://docs.tagshelf.dev/ +This library serves as a wrapper for our REST API, which you can find the documentation for in this link https://docs.tagshelf.dev/ ## Alfred