feat: initial commit

Author: Yakiyo

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest 
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@v1.3
+        with:
+          sdk: '2.18.3'
+
+      - name: Install Dependencies
+        run: dart pub get
+
+      - name: Check Code Format
+        run: dart format --output=none --set-exit-if-changed .
+
+      - name: Analyze Code
+        run: dart analyze
+
+      - name: Run Test
+        run: dart test

.gitignore

@@ -0,0 +1,16 @@
+# Files and directories created by pub.
+.dart_tool/
+.packages
+
+# Conventional directory for build outputs.
+build/
+
+# Omit committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock
+
+# Env files
+.env
+
+# Dev testing file
+dev.dart

.hooks/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+
+dart format --output=none --set-exit-if-changed .
+dart test

CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial version.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Yakiyo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,60 @@
+# SRA - Some Random Api
+[![CI](https://github.com/Yakiyo/sra.dart/actions/workflows/ci.yml/badge.svg)]() [![Pub Package](https://img.shields.io/pub/v/sra.svg)](https://pub.dev/packages/sra)
+
+Minimal Dart wrapper to interact with [Some Random Api](https://some-random-api.ml). Easy to use, simplified and lightweight.
+
+## Getting started
+
+Add the package to your project.
+```bash
+$ dart pub add sra
+```
+
+## Usage
+
+Import the package to your file/project.
+
+```dart
+import 'package:sra/sra.dart' as sra;
+```
+The package exports a base `Client` class which is the central spot for interacting with the api. The client class itself has only one public method `fetch`.
+```dart
+import 'package:sra/sra.dart' show Client;
+
+void main() async {
+    var client = Client();
+    // Optionally pass the api key on class initiation
+    // Example: Client(apiKey);
+    var res = await client.fetch('/animal/dog');
+    print(res);
+}
+```
+The fetch method takes 1 mandatory argument of type String, the endpoint path. You can optionally pass query parameters to the function (if the endpoint requires so). For endpoints that have some required parameters, if you don't specify one of them, the function throws an error.
+```dart
+// Fetching with parameters
+client.fetch('/canvas/misc/oogway', {
+    'quote': 'Nothing is a mistake'
+});
+// The endpoint doesn't need any parameters so we don't
+// need to provide anything else
+client.fetch('/animal/dog');
+// This throws an error, because the lied endpoint
+// requires a mandatory parameter called 'avatar' which
+// is not specified here, so it'll throw an error.
+client.fetch('/canvas/misc/lied', {
+    'username': 'Yakiyo'
+});
+```
+The fetch method returns `Object` which can be one of the two types, a `Map<String, String>` or `List<int>`. Endpoints that return a json result return Map, while endpoints that return PNG images return a `List<U8int>` or a buffer that can be used to write to a file (see [fetch_binary.dart](./example/fetch_binary.dart)). Detailed usages can be found in the [example/](./example/) directory. Feel free to ping me (Yakiyo#1206) in the [SRA Discord Server](https://discord.gg/tTUMWFd) for help, questions or anything.
+
+All valid endpoints and their required/optional arguments are availabale in [SRA docs](https://some-random-api.ml/docs). Currently only the [Rank Card](https://some-random-api.ml/docs/premium#rank-card), [Welcome Image (premium)](https://some-random-api.ml/docs/premium#welcome-images) and [Welcome Image (free)](https://some-random-api.ml/docs/welcome#welcome-images%20(free)) are unavailable in the package. To be added soon:tm:.
+## Contribution and Issues
+
+For any issues or bugs, please file a new issue [here](https://github.com/Yakiyo/sra.dart/issues/).
+
+All contributions are welcome. Before creating a Pull Request or working on a new feature, please open up an issue so that it can be discussed.
+
+## Author
+**sra.dart** © [Yakiyo](https://github.com/Yakiyo). Authored and maintained by Yakiyo.
+
+Released under [MIT](https://opensource.org/licenses/MIT) License

analysis_options.yaml

@@ -0,0 +1,30 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+# Uncomment the following section to specify additional rules.
+
+# linter:
+#   rules:
+#     - camel_case_types
+
+# analyzer:
+#   exclude:
+#     - path/to/excluded/files/**
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options

example/apikey.dart

@@ -0,0 +1,15 @@
+import 'dart:io' show Platform;
+import 'package:sra/sra.dart' as sra;
+
+void main() async {
+  var env = Platform.environment; // Import the env variables
+  // Initialize the client with an api on contructing it
+  var client = sra.Client(env['SRA_TOKEN']);
+  // You can access premium commands with it now. Otherwise it would have thrown an error.
+  client.fetch('/premium/amongus', {
+    'avatar':
+        'https://cdn.discordapp.com/avatars/235148962103951360/ed3dac3b6e7a851df781632a4295fcb9.png?size=1024',
+    'username': 'Carl',
+    'custom': 'Yeet'
+  });
+}

example/fetch.dart

@@ -0,0 +1,14 @@
+import 'package:sra/sra.dart' as sra;
+
+void main() async {
+  var client = sra.Client();
+
+  var res = await client.fetch('/animal/dog');
+
+  // Check if res is Map or not. If it isn't, then something went wrong.
+  if (res is Map) {
+    print(res);
+  } else {
+    throw 'res should be a map since /animal/dog endpoint returns json result';
+  }
+}

example/fetch_binary.dart

@@ -0,0 +1,23 @@
+import 'package:sra/sra.dart' as sra;
+import 'dart:io' as io;
+
+void main() async {
+  var client = sra.Client();
+
+  var res = await client.fetch('/canvas/misc/youtube-comment', {
+    'avatar':
+        'https://cdn.discordapp.com/avatars/235148962103951360/ed3dac3b6e7a851df781632a4295fcb9.png?size=1024',
+    // No, I wasn't paid to advertise carl, I just like it myself.
+    'comment': 'Visit https://carl.gg',
+    'username': 'Carl'
+  });
+
+  // Endpoints that return binary data (image files) will always return
+  // a List<U8int> object. If it isn't a list, then something went wrong
+  if (res is List<int>) {
+    // Write the result to a file.
+    io.File("./img.png").writeAsBytesSync(res);
+  } else {
+    throw 'Unexpected error. Received $res';
+  }
+}

example/fetch_query.dart

@@ -0,0 +1,18 @@
+import 'package:sra/sra.dart' as sra;
+import 'dart:io' as io;
+
+void main() async {
+  var client = sra.Client();
+
+  // Pass the query parameters as Map<String, String> to the function
+  var res = await client.fetch('/canvas/overlay/glass', {
+    'avatar':
+        'https://cdn.discordapp.com/avatars/235148962103951360/ed3dac3b6e7a851df781632a4295fcb9.png?size=1024',
+  });
+  if (res is List<int>) {
+    // Write the result to a file.
+    io.File("./img.png").writeAsBytesSync(res);
+  } else {
+    throw 'Unexpected error. Received $res';
+  }
+}

lib/sra.dart

@@ -0,0 +1,7 @@
+/// Dart wrapper for interacting with Some Random Api.
+///
+/// Easy to use, simplified and fast methods
+library sra;
+
+export 'src/client.dart' show Client;
+export 'src/endpoint.dart' show Endpoint, EndpointQuery;

lib/src/client.dart

@@ -0,0 +1,82 @@
+import 'dart:convert' show jsonDecode;
+import 'package:http/http.dart' show get;
+import './endpoint.dart';
+import './util.dart';
+
+/// Base class to interact with the api
+class Client {
+  final baseUrl = 'some-random-api.ml';
+  late final Map<String, Endpoint> endpoints;
+  late final String? apiKey;
+
+  /// Pass the api key if available on constructing. If its provided, the key
+  /// is passed along all the requests. If no key is provided, premium endpoints
+  /// will throw an error.
+  Client([this.apiKey]) {
+    _loadEndpoints();
+  }
+
+  void _loadEndpoints() {
+    endpoints = <String, Endpoint>{};
+    loadEndpoints(endpoints);
+  }
+
+  /// Fetch data from an endpoint
+  ///
+  /// path - the endpoint to fetch from, endpoint must include its category
+  /// example: '/img/dog'
+  /// query - a map of query parameters to be passed along with the request.
+  Future<Object> fetch(String path, [Map<String, String>? query]) async {
+    if (!path.startsWith('/')) {
+      path = '/$path';
+    }
+    if (!endpoints.containsKey(path)) {
+      throw "Invalid endpoint provided.";
+    }
+    var endpoint = endpoints[path] as Endpoint;
+    if (query != null && apiKey != null) {
+      query['key'] = apiKey as String;
+    }
+    var url = Uri.https(baseUrl, path, query);
+    _validateRequest(endpoint, query);
+    try {
+      var res = await get(url);
+      var type = res.headers['content-type'] ?? 'application/json';
+      if (type.contains('application/json')) {
+        var out = jsonDecode(res.body);
+        if (out['error'] != null) {
+          throw out['error'];
+        } else if (res.statusCode != 200) {
+          throw 'Internal error when fetching from api. Got status code ${res.statusCode}';
+        }
+        return out;
+      } else if (type.contains('image')) {
+        return res.bodyBytes;
+      }
+      // Dart throws error if a default return is not provided. As long as the api works, the
+      // return type should always be either a json or image data and this would not be required.
+      throw 'Unexpected error, api did not return expected type. Got $res';
+    } catch (e) {
+      rethrow;
+    }
+  }
+
+  // This was messy af to write
+  void _validateRequest(Endpoint endpoint, Map<String, String>? query) {
+    if (endpoint.isPremium && apiKey == null) {
+      throw 'Endpoint \'${endpoint.path}\' is premium and requires an api key to work';
+    }
+    if (endpoint.query.isNotEmpty) {
+      if (query == null || query.isEmpty) {
+        throw 'Endpoint "${endpoint.path}" requires query parameters but was provided none';
+      }
+      var keys = endpoint.query.keys;
+      for (final key in keys) {
+        final k = endpoint.query[key] as EndpointQuery;
+        if (k.required && !query.containsKey(k.key)) {
+          throw 'Query parameter ${k.key} is required but was not provided';
+        }
+      }
+    }
+  }
+}

lib/src/endpoint.dart

@@ -0,0 +1,41 @@
+/// Represents a Endpoint
+///
+/// path - the endpoint path
+/// isPremium - wether the endpoint is premium or not
+/// query - a map of all the arguments of the endpoint
+class Endpoint {
+  late final Map<String, EndpointQuery> query = {};
+  late final bool isPremium;
+  late final String path;
+  Endpoint(this.path, [List<Map<String, dynamic>>? queries, bool? premium]) {
+    if (premium != null) {
+      isPremium = premium;
+    } else {
+      isPremium = false;
+    }
+    if (queries != null && queries.isNotEmpty) {
+      for (var element in queries) {
+        var val = EndpointQuery(element);
+        query[val.key] = val;
+      }
+    }
+  }
+}
+
+/// Represents a class of an Endpoint's query
+///
+/// Using a class makes it easier then using
+/// a map.
+/// Key - the query key
+/// required - wether the query is must or not
+class EndpointQuery {
+  late final String key;
+  late bool required = false;
+  EndpointQuery(Map<String, dynamic> query) {
+    key = query['key'] as String;
+    var cond = query['required'];
+    if (cond is bool) {
+      required = cond;
+    }
+  }
+}